Introduction

Most API documentation fails in the same way: it describes the API accurately and is still useless. The endpoints are listed, the parameters are typed, and yet a developer making their first call spends an hour guessing — which header carries the token, what a 422 means, whether the id in the response is the same id the next endpoint expects.

Good API documentation is not a description of your API. It is a tool that gets a stranger from zero to a working integration as fast as possible, and keeps them working when something goes wrong. That is the standard this guide is built around.

The practices below were checked against current API documentation guides and standards in November 2026, including the OpenAPI 3.2 specification (published September 2025, with a 3.2.1 patch in September 2026) and RFC 9457 for error responses.

Start with the audience, not the endpoints

Before you write a word, answer three questions:

1. Who is reading this? A developer integrating your API for the first time is not the same reader as your own teammate debugging a production issue. Most public API docs serve the first reader. Write for them first.
2. What is their first job? Usually it is one thing: make a successful API call, then do the one task they came for — create a user, list orders, send a message. Organize your docs around getting that job done.
3. What do they already know? Assume they know HTTP and JSON, but do not assume they know your domain. Explain your concepts — what an “article,” a “workspace,” or a “charge” is in your system — before you ask them to use those concepts in a request.

This audience-first thinking is the same principle behind our guide to improving documentation: docs exist for the reader’s task, not for the writer’s completeness.

The structure: four layers that cover everything

A complete API documentation set has four layers, and the order matters — each assumes the one before it. 1. Overview: what the API does, who it is for, the base URL (for example, https://api.example.com/v1), the protocol (HTTPS only — no exceptions in 2026), the response format (usually JSON), and the versioning scheme. If your API has sandbox and production environments, list both here with a clear note on how they differ. 2. Getting started: how to get credentials, authenticate, and make a first successful call. This page deserves the most care of anything you will write — if a developer cannot complete it, nothing else in your docs matters. 3. Endpoint reference: every endpoint with its method, path, parameters, schemas, examples, and errors. 4. Guides and concepts: pagination, rate limits, webhooks, versioning, changelog, and migration guides.

Keep the overview to two paragraphs. Missing any layer breaks the developer experience: without the overview they do not know what the API is for, without getting started they cannot make a first call, without the reference they cannot build the integration, and without the guides they get stuck on the details.

Documenting authentication so nobody gets stuck

Authentication is where most developers get stuck first, so give it a dedicated section covering every method your API supports — API keys, OAuth 2.0, JWT — with complete code examples for each.

For every method, document four things:

• How to obtain credentials. Where do developers create an API key or register an OAuth application? Link directly to that page. Do not make them hunt for it.
• Exactly where the credential goes. Show the exact header, not a vague description. Most commonly it is the Authorization: Bearer <token> header. Show a full example request, not just the header in isolation.
• Token lifecycle. Do tokens expire? How are they refreshed? What scopes or permissions can a token have, and what happens when a token lacks the scope an endpoint needs?
• What failure looks like. Show the error a developer gets when the token is missing, expired, or wrong — including the exact status code and response body. Most first-call failures are authentication failures, and a developer who can recognize the error can fix it in seconds instead of opening a support ticket.

The endpoint reference: a template for every endpoint

The endpoint reference is the core of your documentation, and consistency is what makes it usable. Use the same template for every endpoint so developers always know where to look. A solid template has nine parts: HTTP method and path; a one-sentence description; authentication requirements and scopes; path parameters; query parameters; the request body schema; a complete example request; at least two example responses (success and the most common error); and every status code the endpoint can return.

The request-response pair is the unit of trust in API docs. Never document an endpoint without both. A schema table alone does not show a developer what a real call looks like; an example alone does not show them the edge cases. They need both, side by side.

For example, a GET /v1/articles/{id} entry should show the method and path, a one-sentence description, the id path parameter, a complete example request with the Authorization header carrying the developer’s token, the success response (200 OK) with its fields, and the errors it can return — 401 for a missing or invalid token, 404 for an unknown article ID. Group endpoints logically — by resource or by task — rather than alphabetically. Developers think in terms of “I need to work with articles,” not “I need the endpoint whose path starts with G.”

Code examples: the single most valuable element

Code examples are the single most valuable element in API documentation. Developers do not want to read paragraphs about how a request works — they want to see a working request they can copy, adapt, and run. Every example should be complete (copy it, swap in credentials, run it), realistic (real-looking values, not foo and bar — placeholder values have a way of surviving into production code), and paired with its response, which is where developers learn your field names, nesting, date format, and pagination envelope.

If you can, offer a live “try it” console that fires real requests from the browser. It removes the round trip between the docs and a tool like Postman, which is the single biggest friction point for new integrators. If you cannot offer one, at minimum provide examples in the languages your audience actually uses — usually cURL plus one or two popular languages — and keep them tested. An example that no longer works is worse than no example, because it teaches the developer to distrust the rest of the docs.

Error codes: document the unhappy path as carefully as the happy one

Most API docs only document success. That is a mistake, because developers integrating in production spend most of their debugging time on errors. Document every error code your API returns, what it means, and what the client should do about it — starting with the standard HTTP status codes and their meanings in your system:

Status	Meaning	What the developer should do
200 OK	Request succeeded	Read the response body
201 Created	A new resource was created	Read the returned resource, including its ID
400 Bad Request	Malformed request or failed validation	Check the error details in the body; fix the request
401 Unauthorized	Authentication missing or invalid	Check the token; get a new one if expired
403 Forbidden	Authenticated, but lacking permission	Check the token’s scopes or the account’s role
404 Not Found	The resource does not exist	Check the ID; do not retry with the same ID
409 Conflict	The request conflicts with existing data	The resource may already exist
422 Unprocessable Entity	Understood but failed validation	Read the field-level errors in the body
429 Too Many Requests	Rate limit exceeded	Wait for the Retry-After time, then retry
500 Internal Server Error	Something went wrong on your side	Retry with backoff; report it if it persists

One distinction deserves special attention: 401 vs 403. A 401 means “I don’t know who you are” — the token is missing, expired, or invalid. A 403 means “I know who you are, and you are not allowed” — the token is valid but lacks the scope or role. State this explicitly; it saves a support ticket every time.

Use one error format across the whole API, and document it. RFC 9457 problem details (application/problem+json) is the current standard choice. Every error response should include a machine-readable code, a human-readable message, and — for validation errors — which fields failed and why. And create a dedicated error reference page that catalogs all possible errors: developers hitting an error will search for the error code, so make sure they find a helpful result.

Rate limits, pagination, and the other “boring” sections

The sections developers skip while reading and desperately need while debugging are rate limits, pagination, and filtering. Document them all, in one place each, and link to them from every endpoint that uses them.

• Rate limits: the limits, how they are calculated (per minute, per hour, per API key), which headers show current usage, and what happens when exceeded — including whether a 429 carries a Retry-After header.
• Pagination: which style you use (offset, cursor, or page number), the default and maximum page size, and how the response signals more pages. Show a full example of fetching page two.
• Filtering and sorting: which fields can be filtered or sorted, the query parameter syntax, and what happens with an invalid filter value — an error, or silently ignored?
• Webhooks, if you have them: which events exist, the payload format, how to verify the signature, and the retry policy when delivery fails.

These sections are short to write and save enormous amounts of support time. The reason they are often missing is that the API author already knows the answers and forgets that nobody else does.

Versioning, changelogs, and deprecations

APIs change, and developers need to know what changed, when, and whether their integration will break. Document three things:

• Your versioning strategy. How are versions specified — URL path (/v1/), header, or query parameter? What counts as a breaking change? How long are older versions supported, and how will consumers be told when a version is ending?
• A changelog. Maintain a dated changelog that lists every API change, so developers can track what changed and plan their updates. Our guide to writing a changelog covers the format — the same principles apply here, with one addition: every entry should say whether the change is breaking.
• Deprecations, stated plainly. When an endpoint or field is being replaced, say so in the docs for that endpoint: what is deprecated, why, what should be used instead, and the planned removal date. Mark deprecated endpoints in your specification (deprecated: true in OpenAPI) so the generated docs show the warning automatically.

Publish docs per API version. A developer on v1 should be reading v1 docs, not the current version’s docs with a note saying “this changed in v2.” And note that API versioning and software release versioning are related but not the same thing — your API may be at v1 while your project releases follow Semantic Versioning — so document each on its own terms.

Keeping documentation current

Outdated documentation erodes trust faster than missing documentation, because it teaches developers that your docs cannot be relied on. Three habits keep docs current:

1. Generate the reference from your API specification. If you have an OpenAPI description, generate the reference documentation from it with a tool like Swagger UI, Redoc, or Scalar. The specification becomes the single source of truth, and the docs cannot drift from the code. Write the OpenAPI description first, and treat it as part of the API, not an afterthought.
2. Keep documentation in version control, next to the code. When a pull request adds an endpoint, the same pull request should add its documentation. The same discipline applies to the README and to commit messages: good commit messages make it possible to trace when and why a documented behavior changed.
3. Review docs as part of the release process. Before a release ships, someone who did not write the change should read the affected docs pages and try the examples. A five-minute check catches the renamed field, the new required parameter, and the outdated example that would otherwise cost your users an hour each.

Finally, make feedback easy. A “was this page helpful?” link or a “report an error in these docs” link at the bottom of every page turns your readers into your proofreaders.

A checklist before you publish your docs

Before your API documentation goes live, run through this list:

• A new developer can go from the overview to a successful first call in under fifteen minutes
• Every endpoint has a method, path, description, parameters, request example, response example, and error list
• Authentication is shown as a complete, copy-pasteable example, including what failure looks like
• Every error code has a meaning and a recommended action; 401 and 403 are distinguished
• Rate limits, pagination, and filtering are documented in one place each
• Versioning, changelog, and deprecation policy are stated
• Every code example has been run against the current API and works
• The docs are in version control and update with the code

FAQ

Should I write API documentation by hand or generate it from a specification?
Both. Generate the endpoint reference from an OpenAPI specification so it stays accurate, and hand-write the overview, getting-started guide, and conceptual guides — those are the parts that need judgment about what a new developer needs first, and no generator writes them well.

How do I document an API that is still changing rapidly?
Version it from the start, even at v0 or v1, and keep a changelog from day one. Mark experimental endpoints clearly, and say what “experimental” means — can it change without notice? For how long? Developers can work with a changing API; what they cannot work with is a changing API that pretends to be stable.

Do I need to document internal APIs?
Yes, if anyone other than the author uses them. Internal APIs with no docs become knowledge that lives in one person’s head, and that person eventually goes on leave. The same structure applies — it can be shorter, but it should still exist.

The bottom line

Write for the developer’s first task, not for your API’s completeness. Give them a getting-started guide that produces a working call in minutes, an endpoint reference that follows the same template every time, authentication they can copy and paste, errors they can diagnose without contacting you, and a changelog that says what changed and whether it breaks anything. Keep the docs in version control with the code, generate the reference from your specification, and test every example before every release. Documentation a developer can actually use is documentation that gets your API adopted — everything else is a description of an API nobody integrates with.