API Documentation Craft

Parent: Writing and Documentation · researched 2026-05-29T18:28:37.054Z· 10 sources · 10 concepts · skill api-docs-craft

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

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. [source]

1. Diátaxis — the four-quadrant framework

Tutorial: For a beginner. Guarantees a successful outcome. Concrete, specific, opinionated. [source]
How-to guide: For a competent user with a specific task. Goal-oriented. [source]
Reference: For a developer looking up the exact shape. Comprehensive, accurate, terse. No narrative. [source]
Explanation: For a curious developer who wants the why. Discursive, opinionated. [source]
The fatal mistake: mixing types on one page. [source]

2. Endpoint reference page — the canonical structure

HTTP method + path as the page title [source]
One-paragraph summary [source]
Request: required vs optional parameters [source]
Request body schema [source]
Response schema [source]
Status codes: every status this endpoint can return [source]
Errors: structured error codes, each linked to the error catalog [source]
Code samples: the same call in 4-8 languages [source]
"Try it" widget [source]
Idempotency, rate limits, scopes/permissions [source]
Related endpoints [source]

3. Code samples — discipline, not decoration

Multiple languages. Minimum: curl + Node/Python + one strongly-typed language. [source]
Language switcher synced across the page. [source]
Use environment variables, not literal secrets. $STRIPE_API_KEY [source]
Show the response. The sample isn't complete without an example response inline. [source]
Runnable in isolation. Each sample includes its imports/requires. [source]

4. Error documentation — the error catalog

Every error code the API can return needs: [source]
The HTTP status code [source]
The machine-readable error code [source]
The human-readable message [source]
The trigger condition [source]
The remediation - what the developer should do [source]

5. Deprecation banner pattern — RFC 8594 `Sunset` and `Deprecation`

Visible banner in docs: [source]

6. API versioning strategies

URI path versioning (/v1/, /v2/): Visible in URL, easy to route. [source]
Header versioning: Accept: application/vnd.example.v2+json [source]
Date-pinned versioning (Stripe): Stripe-Version: 2024-10-01 [source]

8. The "explanation" quadrant — where most docs starve

Most docs sites do reference and tutorials well. They skip explanation entirely. [source]
"Why our IDs are prefixed" [source]
"How idempotency keys work" [source]
"Date-based versioning explained" [source]

9. The "Getting started" path — tutorial-first

Install the SDK (one command). [source]
Set an environment variable with the test API key. [source]
Make a first call (one copy-paste). [source]
See the response. Confirm success. [source]

Anti-Patterns

Mixing Diátaxis quadrants on one page [source]
Code samples without runnable context [source]
Single-language code samples [source]
No error catalog [source]
Deprecation messages only in the changelog [source]
No "Getting started" tutorial [source]

References

Diátaxis - official site [source]
Stripe API Reference [source]
RFC 8594 - The Sunset HTTP Header Field [source]
OpenAPI Specification 3.1 [source]

Children

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)
10-minute Getting Started tutorial (frontier)

Frontier under this node: 10-minute Getting Started tutorial, 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

← the whole tree · 3D view· how to read this page