Two lines into a reference page, a developer should know whether this endpoint can do the job. Too often they get a route name, a URL, and a shrug. They then spend twenty minutes guessing whether the timestamp is in seconds or milliseconds, whether a field can be null, and what actually happens when the token expires.
The checklist below covers fifteen elements. None of them are exotic. Together they turn a route listing into documentation someone can build against without opening a support ticket first.
Before the details, decide who you are writing for
Two readers show up on every API page. The first is an integrator with a deadline: they want the happy path, a copyable example, and the shape of the response. The second is a maintainer debugging at 2 a.m.: they want error codes, edge cases, defaults, and the exact type of every field.
Both are served by the same rule. Answer the common question first, then go deep. Purpose and a working example belong near the top; exhaustive field tables belong below them. Nobody reads a reference page from start to finish, so make it skimmable and predictable instead.
Endpoint basics: elements 1 to 5
These five items establish what the endpoint is and how to reach it.
- A one-sentence purpose. Not "Gets orders" but "Returns all orders for the authenticated account, newest first." Say what it does and what comes back.
- The complete path, including base URL and version. GET https://api.example.com/v1/orders/{orderId} beats GET /orders. Developers should never have to assemble the URL themselves.
- The HTTP method and its behaviour. State whether the call is safe or idempotent, and whether retrying after a timeout is allowed. This single line prevents duplicate charges and duplicate emails.
- Authentication requirements. Name the scheme (API key header, OAuth 2.0 bearer token, signed request), the scopes or permissions needed, and what the caller sees when a credential is missing or expired.
- Required headers. Content-Type, Accept, idempotency keys, tenant identifiers — anything the server rejects a request without.
Requests: elements 6 to 8
Parameters are where documentation quietly falls apart. A table with a name and the word "string" is not enough.
- 6. Parameters and their contracts. For every path, query, and body parameter, list the type, whether it is required, the default value, the allowed range or enum, and an example. If the default is null, write "null" rather than leaving the cell empty. Note how repeated query parameters are handled — comma-separated, or repeated keys.
- 7. The request body schema. Show nesting, mark required fields, and say which fields are ignored on update. If two fields are mutually exclusive, spell that out. If a value is trimmed or normalised on the way in, mention it.
- 8. One complete request example. A real curl call with a dummy payload and the headers included. Developers copy it, swap the IDs, and run it. If it fails because you left out the auth header, they will blame the API, not the docs.
Where it helps, add a second, shorter example for the most common variation: the minimal request with only required fields.
Responses and errors: elements 9 to 12
- 9. A success example with an actual body, not a schema alone. Include realistic values so the shape is obvious at a glance. If the endpoint returns 204 No Content, say so instead of showing an empty JSON object.
- 10. Field-level descriptions. Type, format, nullability, and units. "amount: integer, smallest currency unit" saves a surprising amount of back-and-forth. Mark timestamps as ISO 8601 UTC and say whether they are strings or numbers.
- 11. Error bodies documented as thoroughly as success bodies. Every error needs a stable machine-readable code, a human-readable message, a description of the cause, and a note on the fix. INVALID_CURSOR means nothing without "the cursor expired after 24 hours; restart from the first page."
- 12. A status code table. List every code the endpoint can return — 200, 201, 204, 400, 401, 403, 404, 409, 422, 429, 500 — with the condition that triggers each one. Stopping at the happy path leaves the most common failure modes undescribed.
A useful habit: if a client can receive it, the documentation should mention it.
Operational details: elements 13 to 15
- 13. Rate limits. The limit, the window, the response headers that report remaining quota, and the behaviour when a caller exceeds it. If you return 429, document whether a Retry-After header is sent and whether limits apply per key, per IP, or per account.
- 14. Pagination, filtering, and sorting. Which parameters exist, whether the cursor is opaque, the maximum page size, and how a client knows there are no more results.
- 15. Versioning, deprecation, and a way to ask questions. Explain how breaking changes are announced, how long older versions stay live, the deprecation timeline, and where to reach a human. A changelog entry per release is cheap and saves everyone time.
Formatting habits that keep documentation usable
Content aside, presentation decides whether anyone finds what they need.
- Keep the same section order on every endpoint page. Predictability is a feature.
- Write in the second person and active voice: "Send the token in the Authorization header."
- Format anything a developer will type as code, including header names and enum values.
- Test every example in a fresh environment before publishing. A copy-paste error costs more trust than a missing page.
- Break up nested conditionals. A sentence with three "if"s belongs in a list.
Publish, then keep the promise
Documentation is not finished at launch. Wire the reference into your release process: when a pull request changes a response shape, a parameter default, or a status code, the matching page changes in the same review. Add a small test that runs your published snippets against a staging server. When an example breaks, you find out before your users do.
Then run the ten-minute pass before any endpoint page goes live. Ask one question: could a developer call this endpoint successfully using only what is on this page? If the answer is not an immediate yes, you have just found your next edit.
Photo: stevepb / Pixabay
