API reference

Reference is not a guide

Readers come to documentation with different needs. A guide teaches: it walks through a task in order and explains why. A reference answers a precise question fast: what does this parameter accept, what does this call return, which error means what.

Mixing the two serves neither. A guide padded with every optional field becomes hard to follow; a reference written as narrative becomes hard to search. Most products need both, kept separate and linked.

What a complete entry contains

• The signature — the endpoint and method, or the function name, exactly as it is called
• Every parameter — name, type, whether it is required, its default and its limits
• The return — the response shape or return type, including fields that are only sometimes present
• Errors — what comes back when the call fails, and what each error means
• An example — a request and response a reader can run as written

An entry missing errors is the most common gap. It is also the one readers hit at the worst moment.

Why references go stale fastest

A reference is the most detailed part of documentation, so it has the most claims that a code change can break. Rename a parameter, tighten a limit, add a response field, split an error code — each one silently invalidates a line somewhere in the reference. Nothing fails a build when that happens, which is how drift starts.

Derived from the source

Because almost everything in a reference is a fact about the code, it is the part of documentation best derived from the code — from the source itself or from a specification such as OpenAPI — rather than maintained by hand. A reference derived from the source can be regenerated when the code changes and checked against it; one typed by hand depends on someone remembering.