API Documentation Craft
API Documentation Craft
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.
Core Concepts
1. Diátaxis — the four-quadrant framework
| Practical steps (action) | Theoretical knowledge (cognition) | |
|---|---|---|
| When learning | Tutorials | Explanation |
| When working | How-to guides | Reference |
Tutorial: For a beginner. Guarantees a successful outcome. Concrete, specific, opinionated.
How-to guide: For a competent user with a specific task. Goal-oriented.
Reference: For a developer looking up the exact shape. Comprehensive, accurate, terse. No narrative.
Explanation: For a curious developer who wants the why. Discursive, opinionated.
The fatal mistake: mixing types on one page.
2. Endpoint reference page — the canonical structure
- HTTP method + path as the page title
- One-paragraph summary
- Request: required vs optional parameters
- Request body schema
- Response schema
- Status codes: every status this endpoint can return
- Errors: structured error codes, each linked to the error catalog
- Code samples: the same call in 4-8 languages
- “Try it” widget
- Idempotency, rate limits, scopes/permissions
- Related endpoints
3. Code samples — discipline, not decoration
- Multiple languages. Minimum: curl + Node/Python + one strongly-typed language.
- Language switcher synced across the page.
- Use environment variables, not literal secrets.
$STRIPE_API_KEY - Show the response. The sample isn’t complete without an example response inline.
- Runnable in isolation. Each sample includes its imports/requires.
4. Error documentation — the error catalog
Every error code the API can return needs:
- The HTTP status code
- The machine-readable error code
- The human-readable message
- The trigger condition
- The remediation — what the developer should do
5. Deprecation banner pattern — RFC 8594 Sunset and Deprecation
HTTP headers:
Deprecation: Sun, 11 Nov 2026 23:59:59 GMT
Sunset: Sat, 11 May 2027 23:59:59 GMT
Link: <https://api.example.com/docs/migration/v1-to-v2>; rel="sunset"Visible banner in docs:
> ⚠️ **Deprecated 2026-11-11. Sunsets 2027-05-11.**
>
> This endpoint will return `410 Gone` after the sunset date.
> Migrate to [`POST /v2/charges`](../v2/charges).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
7. OpenAPI / Swagger UX — three-pane layout
| Left pane | Center pane | Right pane |
|---|---|---|
| Navigation | Prose + parameters | Live code samples + interactive request |
8. The “explanation” quadrant — where most docs starve
Most docs sites do reference and tutorials well. They skip explanation entirely.
Examples:
- “Why our IDs are prefixed”
- “How idempotency keys work”
- “Date-based versioning explained”
9. The “Getting started” path — tutorial-first
10-minute tutorial:
- Install the SDK (one command).
- Set an environment variable with the test API key.
- Make a first call (one copy-paste).
- See the response. Confirm success.
Anti-Patterns
- Mixing Diátaxis quadrants on one page
- Code samples without runnable context
- Single-language code samples
- No error catalog
- Deprecation messages only in the changelog
- No “Getting started” tutorial