API Documentation and Reference Template

Each part answers a different question, so keep them apart. A quickstart teaches a newcomer; a reference page describes one endpoint completely. Daniele Procida, who created the Diátaxis documentation framework, warns that too many software developers think that auto-generated reference material is all the documentation required¹.

If you have an OpenAPI file, use it as your inventory, but know its limits. In the OpenAPI Specification, a list of responses needs only one response code², and a lone code should be the success response. So a spec file can be valid while declaring no errors at all.

The specification still expects documentation to cover "a successful operation response and any known errors." A catch-all default response with a one-line description falls short: it tells readers that failures exist, not what they look like. A linter can flag the gap. Redocly, which sells API documentation tools, has a rule in its recommended settings that warns when an operation has no 4xx error response³.

Then compare the file with what's running: your routes, your gateway config and a week of access logs. An endpoint that shipped without making it into the spec is invisible to every generator. Add each one you find, or mark it internal.

Developers learn where to look once, so give every endpoint page the same order. Define shared fields once, too: if a field like status appears on several endpoints, explain it in one place, such as a data dictionary, and link to it.

• Summary: one sentence on what the call does
• Authentication: the scheme and the exact scope it needs
• Parameters: type, whether required, and units
• Request and response examples that work as printed
• Errors: every type the call can return
• Rate limit, and what happens when a client hits it

Examples are what developers copy, so one that doesn't match its schema breaks their code. OpenAPI says an example should be compatible with its schema², and leaves tools free to check or not. If nothing checks, an example can keep showing a field you renamed months ago.

Spectral, an open-source linter from the API design company Stoplight, checks examples against their schemas⁴ in its recommended OpenAPI rules and reports a mismatch as an error. Run a check like it on every pull request.

Valid isn't the same as working. An example can match its schema and still fail when sent, because an ID in it has expired or the record it creates already exists. Send each one to a sandbox before you publish, and keep one example per request or response so two copies can't disagree.

One status code often covers several errors that need different handling. RFC 9457, the IETF standard for error details in HTTP APIs, gives each kind of error a type URI. It says consumers must use that URI as the problem type's primary identifier⁵, and treats the status in the body as advisory.

For each error type, the RFC says you must document a type URI, a short title and the status code it goes with. Add the extra fields it carries, what causes it and what the caller should do. The RFC adds that a type URI should lead to documentation on resolving the problem, so make each one open its own entry in your error reference.

Don't invent a type for everything. The RFC says truly generic problems are usually better expressed as plain status codes. A response with no type counts as about:blank, which means the status code says it all, so use it only where that's true.

Write the quickstart once the reference and errors are settled, so it can link to them. Postman, which sells API tools, says the most important API metric is time to first call⁶: how long a new developer takes to make a first successful request.

Keep it to the few calls that produce something real, each ready to copy, with the response it returns. List the scopes the key needs before the first call, and show the failure newcomers hit most, with its fix. Then hand it to a colleague who has never used the API, and time them.

Add a dated changelog entry for anything a working integration could notice: a new required field, a removed field, a new error, a changed limit or a corrected example. Say who is affected and what they need to do.

Deprecations need the most care. OpenAPI's deprecated field² is only true or false, with no room for a date or a replacement, so put those in the changelog. RFC 9745⁷, published in March 2025, defines a Deprecation response header that warns clients at runtime. A Sunset header can add the date the endpoint stops responding.

The template on this page has each of these documents filled in for a made-up shipping API, plus sheets that track endpoints, examples and error types. When a release ships, turn your commits into release notes, and keep the history in a release notes and changelog template.