Card 03/ 07
Documenting an API: Reference, Guides and Examples
A reference says what exists; a guide says how to do a task; an example lets a reader copy and run it.
API documentation answers different questions for different readers, and one kind cannot do the job of another. A reference lists everything that exists, every endpoint, field and error; a guide walks through one task from start to finish; an example is a complete request and response a reader can copy and run. Good API documentation has all three, and generates the reference from the contract.
| Kind | The reader asks | Source |
|---|---|---|
| Reference | What does this field accept, and what errors can this return? | Generated from the OpenAPI document |
| Getting started | How do I make my first successful call? | Written by hand: keys, base URL, one request |
| Task guides | How do I take a payment and handle its failure? | Written by hand, one task each |
| Examples | What exactly do I send, and what comes back? | In the contract, so they appear in the reference and in mocks |
| Changelog and migration guides | What changed, and what must I do? | Written for each release and each deprecation |
Generate the reference. Written by hand, a reference drifts from the API within a release. Generated from the contract, it is right whenever the contract is, and the contract is tested.
Write the guides. A generated reference cannot say which endpoints to call in which order, or what to do when a payment fails. That needs a person who knows the tasks clients come to do.
Make examples runnable. An example with a real base URL for a sandbox, a placeholder key the reader replaces, and the full response, including headers, saves more support questions than any paragraph.
Document the rules a schema cannot hold. Rate limits, retry advice, which errors are safe to retry, how pagination ends, enums that may grow, and the deprecation policy.
So generate what the contract knows, and write by hand what only a person knows.
← → move through sections and cards