Chapter 01 of 10
What Belongs in API Documentation
The pages nearly every API needs beyond the endpoint reference, what each one has to deliver, and how to tell a page that is doing its job from one that only looks complete.
The endpoint reference is the part everybody builds first, and it is never the part that decides whether somebody succeeds. The pages around it are.
The inventory
Nearly every API that people integrate against ends up needing the same small set of pages, because readers get stuck in the same small set of places.
| Page | The question it answers | What makes it fail |
|---|---|---|
| Getting Started | How do I make this work at all? | It stops before a request that actually returns something |
| Authentication | How do I prove who I am? | It shows the header without saying how to get the credential |
| Environments | Which host do I call? | It lists one base URL and leaves the others to support |
| Error Codes | What went wrong and what now? | Status codes with no cause and no action |
| Rate Limits | How hard may I push? | Limits without headers, headers without a retry rule |
| Webhooks | How do I receive events? | Payloads without signature verification |
| Client libraries | Is there something I can install? | Install commands that are a version behind |
| Changelog | Did anything change for me? | A work log rather than a consumer-facing record |
Getting Started has one job
The page has to end in a call that works, and everything on it is either serving that or getting in the way.
That means four things in order. The reader learns what they need before they start, then how to obtain a credential, then which host to send to, then one complete request they can paste. Finish with the response they should see, because a reader who gets something different needs to know immediately that they are off track.
Resist the urge to be complete here. Every concept you introduce on this page is a chance for the reader to stop, and there are nine other pages where that concept fits better.
Authentication answers two questions, not one
Most authentication pages explain how to send the credential and forget to explain how to get one.
Both halves matter, and the acquisition half is where readers stall. Say where the credential is created, what permissions it can carry, how long it lives and what happens when it expires. If tokens are refreshed, show the refresh call in full rather than describing it.
The API authentication guide covers the methods themselves, and security schemes in OpenAPI covers how they are declared in the contract so the reference can render them.
Environments and base URLs
A single host in the documentation is a reasonable default and a common source of support load, because the reader in front of you is usually not in the environment you documented.
List every environment a consumer may legitimately reach, with its base URL and one sentence saying what it is for. Say plainly which one is safe to experiment against, and say what is different about it, since a sandbox that silently skips payment capture will surprise somebody eventually.
Errors need a cause and a way out
An error reference that lists status codes and their standard meanings has documented HTTP rather than your API.
What a reader needs is your application error code, the condition that produced it, and the action that resolves it. A machine-readable error format helps here, because a consistent body shape means a consumer can handle errors generically instead of matching on strings. The problem details format in RFC 9457 is one widely used shape for that, retrieved 2026-09-13.
Rate limits are useless without the retry rule
Publishing a number tells a consumer when they will be rejected. It does not tell them what to do about it.
The useful version has three parts. Name the limit and the window, name the response headers that report the remaining budget, and state the retry behaviour you want, including whether you send Retry-After and whether you expect backoff. Without that third part every consumer invents their own retry loop, and the aggressive ones make your limit worse.
Webhooks are documentation for code you cannot see
With a webhook the roles are reversed, because your consumer writes the receiver and you are the caller.
That makes four things mandatory. Publish the event catalogue with an example payload per event, and publish the signature scheme in enough detail that somebody can verify a request without guessing. Then publish the retry and backoff policy, and say how long you keep retrying before you give up. Delivery order and duplicate delivery deserve a sentence each, because assuming both is the most common integration bug on the receiving side.
The changelog is a consumer document
A changelog written from your sprint is a work log. A changelog written from the contract is a tool.
Entries need a date, a classification the reader can scan, the exact surface that changed, and an action. The changelogs and migration guides chapter of the versioning guide covers the format in full.
In Routebase
Routebase ships the specialized pages as page types rather than as blank documents, so creating a page starts from the structure that page is supposed to have. The set covers Getting Started, Authentication, Environments, Error Codes, Rate Limits, Webhooks, SDKs and Libraries, and the Changelog, and each of them exists once per documentation version.
Every type then opens a template picker with several variants, so a Getting Started page can start minimal with a single cURL example or as a full tutorial with error handling. Organizations can add their own templates on top, which is how a house structure gets applied across projects without anybody copying a page by hand. The page templates guide lists what each variant contains.
Frequently asked questions
What pages should API documentation have?
Beyond the endpoint reference, plan for Getting Started, Authentication, Environments and base URLs, Error Codes, Rate Limits, Webhooks if you send them, client libraries if you ship them, and a Changelog. Each of those exists because a reader gets stuck at that exact point, and every one you leave out becomes a support conversation you have repeatedly.
What should a Getting Started page contain?
It has to end in a request that works. That means the prerequisites, how to get a credential, the base URL for the environment you want people to start in, one complete copyable call, and the response they should see. Anything that does not move the reader toward that first response belongs on a different page.
Do I need an API documentation template?
A template helps because it turns a blank page into a set of questions you already know the answers to. The value is in the section headings rather than the prose, since a reader scanning for the retry rule finds it in the same place on every API that uses the same structure. Write the sections your API actually has and delete the rest.
How much documentation does an internal API need?
Less reference and the same amount of concept. Internal consumers can ask you about a parameter, so the generated reference plus a short Getting Started often covers the mechanical half. What they cannot get by asking is the model behind the API and the rules that are not visible in the schema. That is exactly the part teams skip, because everybody in the room already knows it.
Last reviewed by The Routebase Team.