Reference is the type developers live in. They arrive knowing roughly what they want, and a great reference carries them from ‘what is this’ to ‘I’ve made it work’ without ever forcing them to leave the page and search. The defining habit of a great reference is a simple one: it anticipates the reader’s next question and answers it before they have to ask.
That habit is what separates a reference developers trust from one they abandon. A reference that answers ‘what parameters does this take’ but not ‘what happens when one is invalid’ sends the reader straight to your support queue — and teaches them that your docs can’t be relied on for the hard parts.
The anatomy of an endpoint entry
Every endpoint entry should contain the same parts, in the same order, so that once a reader learns to read one, they can read all of them:
- Method and path, with a one-line statement of what it does. The reader should know in one glance whether they’re in the right place.
- Parameters — each with its type, whether it’s required, its constraints, and its default. Ambiguity here is precisely where integrations break at 2am.
- A complete, runnable request example with a realistic payload — not a fragment with ‘...’ in the middle that the reader has to guess how to fill.
- A real response, showing the shape of the data and a concrete example, including what an empty or paginated result looks like.
- Errors — the status codes this endpoint can return and what each means. This is the section developers need most under pressure, and the one most references omit entirely.
Suppose your reference says: ‘POST /charges creates a charge. Parameters: amount (required), currency (required).’ Before reading on, list the questions a developer will have next.
Likely: What currencies are allowed? Is amount in cents or dollars? What does a success response look like? What happens if the card is declined? Is this idempotent if I retry? A great reference answers every one of those on the same page. Each unanswered question is a support ticket you’ve chosen to receive.
Show, don’t tell
One copy-paste-correct example teaches faster than three paragraphs of prose. A developer will read your example, adapt it, and move on — which is exactly what you want. It also means a broken example is worse than no example at all: it destroys trust instantly and sends the reader away frustrated. Test your examples the way you test code. Better still, generate them from real API calls so they can never silently drift out of date when the API changes.
Consistency is the product
What makes a reference feel professional is not the brilliance of any single page — it is that every page has the same structure, the same order, the same tone. Consistency lets the reader build a mental template once and reuse it across your entire API. Inconsistency forces them to re-learn how to read on every page, which reads as carelessness. Our downloadable API Reference template gives you that structure to fill in and reuse across every endpoint.
A strong GET /users/{id} entry reads: one-line purpose; a parameters table (id — string, required, the user’s unique ID); a full curl request with a real token placeholder; a 200 response with an example body; and an errors table (401 invalid credentials, 404 user not found, 429 rate limited). Nothing is left for the reader to guess. That completeness — repeated identically across every endpoint — is what ‘good API docs’ actually means.
In the age of AI
Reference is where AI is simultaneously most helpful and most dangerous. It will confidently invent parameters, plausible-looking response fields, and error codes that do not exist — because it is pattern-matching what an API usually looks like, not reading yours. Use it to draft the structure and the prose, then verify every single fact against the actual API, ideally by generating your examples and schemas from the source of truth rather than from the model’s imagination. The winning workflow is speed from AI, correctness from your pipeline.
Answer, then press Check. Explanations appear after.
True / FalseA broken code example is better than having no example at all.
Choose oneWhich section do references most often omit but developers need most at 2am?
This lesson is part of Technical Writing Pro
Enrol to unlock all 12 lessons — $149.