API Documentation Craft
Parent: Writing and Documentation · Published reference · snapshot 2026-09-08 · skill technical-writing-craft/references/api-docs-craft.md
↓ Facts as markdownall context files
Produce REST/HTTP API documentation that meets the gold-standard set by Stripe and Twilio: a Diátaxis-organized structure, endpoint reference pages with request/response examples in multiple languages
These notes link each claim to its source. Some citations identify archived research reports that are no longer hosted on this site. A published reference means the content is available; it does not certify independent review or accuracy.Read the editorial policy and follow the sources before relying on a claim.
Overview
- Produce REST/HTTP API documentation that meets the gold-standard set by Stripe and Twilio: a Diátaxis-organized structure, endpoint reference pages with request/response examples in multiple languages, an error-code catalog with troubleshooting steps, deprecation signaling via RFC-8594 headers and visible banners, and an OpenAPI/Swagger interactive layer. [archived source: https://llms-explorer.com/sources/mdb-context-hub/api-docs-craft/#overview]
1. Diátaxis — the four-quadrant framework
- Tutorial: For a beginner. Guarantees a successful outcome. Concrete, specific, opinionated. [archived source: https://llms-explorer.com/sources/mdb-context-hub/api-docs-craft/#1-diátaxis-the-four-quadrant-framework]
- How-to guide: For a competent user with a specific task. Goal-oriented. [archived source: https://llms-explorer.com/sources/mdb-context-hub/api-docs-craft/#1-diátaxis-the-four-quadrant-framework]
- Reference: For a developer looking up the exact shape. Comprehensive, accurate, terse. No narrative. [archived source: https://llms-explorer.com/sources/mdb-context-hub/api-docs-craft/#1-diátaxis-the-four-quadrant-framework]
- Explanation: For a curious developer who wants the why. Discursive, opinionated. [archived source: https://llms-explorer.com/sources/mdb-context-hub/api-docs-craft/#1-diátaxis-the-four-quadrant-framework]
- The fatal mistake: mixing types on one page. [archived source: https://llms-explorer.com/sources/mdb-context-hub/api-docs-craft/#1-diátaxis-the-four-quadrant-framework]
2. Endpoint reference page — the canonical structure
- HTTP method + path as the page title [archived source: https://llms-explorer.com/sources/mdb-context-hub/api-docs-craft/#2-endpoint-reference-page-the-canonical-structure]
- One-paragraph summary [archived source: https://llms-explorer.com/sources/mdb-context-hub/api-docs-craft/#2-endpoint-reference-page-the-canonical-structure]
- Request: required vs optional parameters [archived source: https://llms-explorer.com/sources/mdb-context-hub/api-docs-craft/#2-endpoint-reference-page-the-canonical-structure]
- Status codes: every status this endpoint can return [archived source: https://llms-explorer.com/sources/mdb-context-hub/api-docs-craft/#2-endpoint-reference-page-the-canonical-structure]
- Errors: structured error codes, each linked to the error catalog [archived source: https://llms-explorer.com/sources/mdb-context-hub/api-docs-craft/#2-endpoint-reference-page-the-canonical-structure]
- Code samples: the same call in 4-8 languages [archived source: https://llms-explorer.com/sources/mdb-context-hub/api-docs-craft/#2-endpoint-reference-page-the-canonical-structure]
- Idempotency, rate limits, scopes/permissions [archived source: https://llms-explorer.com/sources/mdb-context-hub/api-docs-craft/#2-endpoint-reference-page-the-canonical-structure]
3. Code samples — discipline, not decoration
- Multiple languages. Minimum: curl + Node/Python + one strongly-typed language. [archived source: https://llms-explorer.com/sources/mdb-context-hub/api-docs-craft/#3-code-samples-discipline-not-decoration]
- Language switcher synced across the page. [archived source: https://llms-explorer.com/sources/mdb-context-hub/api-docs-craft/#3-code-samples-discipline-not-decoration]
- Use environment variables, not literal secrets. $STRIPE_API_KEY [archived source: https://llms-explorer.com/sources/mdb-context-hub/api-docs-craft/#3-code-samples-discipline-not-decoration]
- Show the response. The sample isn't complete without an example response inline. [archived source: https://llms-explorer.com/sources/mdb-context-hub/api-docs-craft/#3-code-samples-discipline-not-decoration]
- Runnable in isolation. Each sample includes its imports/requires. [archived source: https://llms-explorer.com/sources/mdb-context-hub/api-docs-craft/#3-code-samples-discipline-not-decoration]
4. Error documentation — the error catalog
- Every error code the API can return needs: [archived source: https://llms-explorer.com/sources/mdb-context-hub/api-docs-craft/#4-error-documentation-the-error-catalog]
- The machine-readable error code [archived source: https://llms-explorer.com/sources/mdb-context-hub/api-docs-craft/#4-error-documentation-the-error-catalog]
- The human-readable message [archived source: https://llms-explorer.com/sources/mdb-context-hub/api-docs-craft/#4-error-documentation-the-error-catalog]
- The trigger condition [archived source: https://llms-explorer.com/sources/mdb-context-hub/api-docs-craft/#4-error-documentation-the-error-catalog]
- The remediation - what the developer should do [archived source: https://llms-explorer.com/sources/mdb-context-hub/api-docs-craft/#4-error-documentation-the-error-catalog]
5. Deprecation banner pattern — RFC 8594 `Sunset` and `Deprecation`
- Visible banner in docs: [archived source: https://llms-explorer.com/sources/mdb-context-hub/api-docs-craft/#5-deprecation-banner-pattern-rfc-8594-sunset-and-deprecation]
6. API versioning strategies
- URI path versioning (/v1/, /v2/): Visible in URL, easy to route. Header versioning: Accept: application/vnd.example.v2+json Date-pinned versioning (Stripe): Stripe-Version: 2024-10-01 [archived source: https://llms-explorer.com/sources/mdb-context-hub/api-docs-craft/#6-api-versioning-strategies]
8. The "explanation" quadrant — where most docs starve
- Most docs sites do reference and tutorials well. They skip explanation entirely. [archived source: https://llms-explorer.com/sources/mdb-context-hub/api-docs-craft/#8-the-explanation-quadrant-where-most-docs-starve]
- "Why our IDs are prefixed" [archived source: https://llms-explorer.com/sources/mdb-context-hub/api-docs-craft/#8-the-explanation-quadrant-where-most-docs-starve]
- "How idempotency keys work" [archived source: https://llms-explorer.com/sources/mdb-context-hub/api-docs-craft/#8-the-explanation-quadrant-where-most-docs-starve]
- "Date-based versioning explained" [archived source: https://llms-explorer.com/sources/mdb-context-hub/api-docs-craft/#8-the-explanation-quadrant-where-most-docs-starve]
9. The "Getting started" path — tutorial-first
- Install the SDK (one command). [archived source: https://llms-explorer.com/sources/mdb-context-hub/api-docs-craft/#9-the-getting-started-path-tutorial-first]
- Set an environment variable with the test API key. [archived source: https://llms-explorer.com/sources/mdb-context-hub/api-docs-craft/#9-the-getting-started-path-tutorial-first]
- Make a first call (one copy-paste). [archived source: https://llms-explorer.com/sources/mdb-context-hub/api-docs-craft/#9-the-getting-started-path-tutorial-first]
- See the response. Confirm success. [archived source: https://llms-explorer.com/sources/mdb-context-hub/api-docs-craft/#9-the-getting-started-path-tutorial-first]
Anti-Patterns
- Mixing Diátaxis quadrants on one page [archived source: https://llms-explorer.com/sources/mdb-context-hub/api-docs-craft/#anti-patterns]
- Code samples without runnable context [archived source: https://llms-explorer.com/sources/mdb-context-hub/api-docs-craft/#anti-patterns]
- Single-language code samples [archived source: https://llms-explorer.com/sources/mdb-context-hub/api-docs-craft/#anti-patterns]
- Deprecation messages only in the changelog [archived source: https://llms-explorer.com/sources/mdb-context-hub/api-docs-craft/#anti-patterns]
- No "Getting started" tutorial [archived source: https://llms-explorer.com/sources/mdb-context-hub/api-docs-craft/#anti-patterns]
References
- Diátaxis - official site [archived source: https://llms-explorer.com/sources/mdb-context-hub/api-docs-craft/#references]
- Stripe API Reference [archived source: https://llms-explorer.com/sources/mdb-context-hub/api-docs-craft/#references]
- RFC 8594 - The Sunset HTTP Header Field [archived source: https://llms-explorer.com/sources/mdb-context-hub/api-docs-craft/#references]
- OpenAPI Specification 3.1 [archived source: https://llms-explorer.com/sources/mdb-context-hub/api-docs-craft/#references]
Project ideas
- Build an OpenAPI-to-Diataxis generator: auto-produce the Reference quadrant from an OpenAPI 3.1 spec, then hand-write Tutorial/How-to/Explanation around it. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Build a code-sample-matrix linter that checks every documented endpoint has runnable samples in at least curl plus one dynamic plus one typed language, flagging gaps. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Define errors once in a structured file (code, message, trigger, remediation) and generate both the docs error catalog and the API's actual error responses from that one source, so they can't drift apart. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Build a deprecation-banner injector that reads RFC 8594 Sunset/Deprecation headers from a live API and auto-renders the banner on the matching doc page. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
Where this helps
- Any REST/HTTP API aiming for Stripe/Twilio-caliber developer experience, where onboarding friction directly costs adoption. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Documenting an API used across many languages or stacks, where the multi-language code-sample discipline matters most. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- APIs undergoing versioning or deprecation, where RFC 8594 headers plus a visible banner prevent silent breakage for integrators. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Doc sites that skew heavily toward Reference and Tutorial and need a structured push toward the neglected Explanation quadrant. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
Known issues
- The "explanation" quadrant is the one nearly every docs site skips — a review that only checks Reference and Tutorial completeness will miss this every time. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Mixing Diataxis quadrants on one page is the most-cited structural mistake, and it's easy to reintroduce during a rewrite that "simplifies" page structure. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- A code sample missing imports or setup looks complete but silently fails for a developer who copy-pastes it — sample completeness needs its own review pass, separate from checking sample accuracy. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
Children
- 10-minute Getting Started tutorial
- Diátaxis four-quadrant framework (Procida) (frontier)
- Endpoint reference page structure (frontier)
- Multi-language code samples (frontier)
- Error catalog pattern (frontier)
- RFC 8594 Sunset/Deprecation headers (frontier)
- URI vs header vs date-pinned versioning (frontier)
- OpenAPI/Swagger three-pane layout (frontier)
- Try It interactive widgets (frontier)
- Explanation quadrant essays (frontier)
Frontier under this node: Diátaxis four-quadrant framework (Procida), Endpoint reference page structure, Error catalog pattern, Explanation quadrant essays, Multi-language code samples, OpenAPI/Swagger three-pane layout, RFC 8594 Sunset/Deprecation headers, Try It interactive widgets, URI vs header vs date-pinned versioning