How to write an API overview developers can use
Private beta. Access is by waitlist, and paid plans open when the beta ends. Join the waitlist.
An API overview is the first page a developer reads, and often the only one before they decide whether to integrate. It should answer a few questions quickly, and it should sit in the same place, with the same headings, every time.
What to include, in order
- Summary. What the API does, who it is for and one typical use, in two or three sentences.
- Base URL. One line with the version in the path, plus the sandbox URL if there is one.
- Authentication. How to get a key, which header carries it, and whether keys differ per environment.
- Endpoints. A table with method, path, a one-line description, and whether each endpoint is paginated and idempotent. Full parameter details can live in the reference.
- Rate limits. The limit as a number, the headers that report it, and what a client should do when it is exceeded.
- Versioning. What counts as a breaking change and how many days of notice a retired version gets.
- Errors. A table of status codes, error codes, meanings and whether each one is safe to retry.
Mistakes that cost developers time
- Putting authentication on a separate page, so the first call is blocked by a link the reader has to find.
- Listing endpoints without saying which list endpoints are paginated or which writes are idempotent, so a retry can create a duplicate record.
- Documenting the success path only, with no error table, so every client invents its own handling.
- Giving rate limits as "reasonable" or "fair use" instead of a number and a header name.
- Saying nothing about deprecation, so a retired version breaks without warning.
- Letting the layout drift from one API to the next, so developers relearn the page each time they open a new one.
Worked example: Parcel Tracking API
This is a fictional example. The Parcel Tracking API, its keys, IDs, limits and error codes are all invented, but they agree with one another, so you can check each section against the others.
Summary. The Parcel Tracking API lets a merchant create a shipment, read its current status and list the tracking events for each parcel. It is for developers connecting an online shop or warehouse system to shipping labels and delivery updates.
Base URL. https://api.parceltrack.example/v2 for production. The sandbox is https://sandbox.parceltrack.example/v2 and accepts only test keys.
Authentication. Send your API key as a bearer token in the Authorization header: Authorization: Bearer pt_live_.... Keys starting with pt_live_ work only on the production base URL, and keys starting with pt_test_ work only on the sandbox. Create keys under Settings, then API keys. A revoked key returns 401 on its next request.
Endpoints. Every path below is relative to the base URL.
| Method | Path | Description | Paginated | Idempotent |
|---|---|---|---|---|
| POST | /shipments | Create a shipment and receive its tracking number. | no | only with an Idempotency-Key header |
| GET | /shipments/{id} | Read one shipment and its current status. | no | yes |
| GET | /shipments | List the shipments in your account, newest first. | yes | yes |
| GET | /shipments/{id}/events | List the tracking events for one shipment, newest first. | yes | yes |
| POST | /shipments/{id}/cancel | Cancel a shipment that has not been picked up. | no | no |
POST /shipments is idempotent only when you send an Idempotency-Key header. The API keeps that key for 24 hours, and a retry with the same key returns the original shipment instead of creating a second one. Paginated endpoints accept limit (1 to 100, default 25) and cursor, and return next_cursor, which is null on the last page. Cancelling a shipment twice returns 409, so check the status before you retry a cancel.
Rate limits. Production allows 300 requests per minute per API key. The sandbox allows 60 requests per minute per key. Every response includes three headers: RateLimit-Limit (the allowance for the window), RateLimit-Remaining (requests left in the current window) and RateLimit-Reset (seconds until the window resets). Rejected requests count toward the limit.
When a key exceeds its allowance, the API returns 429 with a Retry-After header giving the number of seconds to wait. Wait at least that long, then retry. If requests keep returning 429, back off exponentially starting at 1 second, double the wait on each attempt, add random jitter, and stop after 5 attempts. Do not retry in a tight loop.
Versioning and deprecation. The current version is v2, and it sits in the base URL path. A breaking change is one that can make a working client fail: removing or renaming a field, changing a field's type, changing what an error code means, or making an optional parameter required. Adding endpoints, optional parameters and response fields is not breaking, so clients must ignore response fields they do not recognize. A deprecated version returns a Deprecation header and a Sunset header with the retirement date. Notice is at least 180 days before the Sunset date, and the account owner receives an email when the notice starts.
Errors. Every error returns a JSON body with an error code from the table below and a message for logs. Parse the code, not the message text.
| Status | Error code | Meaning | Safe to retry |
|---|---|---|---|
| 400 | invalid_request | A field is missing or has the wrong format. The body lists each problem under details. | no |
| 401 | unauthorized | The key is missing, revoked, or meant for the other environment. | no |
| 404 | shipment_not_found | No shipment with that ID exists in your account. | no |
| 409 | shipment_state_conflict | The action does not fit the shipment's state, for example cancelling a shipment that has already been picked up. | no |
| 429 | rate_limited | The key has used its allowance for the current minute. | yes, after the Retry-After delay |
| 503 | service_unavailable | Temporary outage. Retry with backoff, and reuse the same Idempotency-Key on POST requests. | yes, with backoff |
Weak versus strong sentences
Three typical sentences from overviews, each followed by a stronger rewrite of the same point.
Weak: "Authentication uses tokens."
Strong: "Send your API key in the Authorization header as Bearer followed by the key. Keys starting with pt_test_ work only on the sandbox, and keys starting with pt_live_ work only on production."
Weak: "Rate limits apply to all endpoints."
Strong: "Each key may send 300 requests per minute to production and 60 to the sandbox. Read RateLimit-Remaining on each response. When you receive a 429, wait the number of seconds in Retry-After before the next request."
Weak: "Lists are paginated."
Strong: "List endpoints return 25 items by default and up to 100 when you pass limit. Pass the next_cursor value from each response as cursor to get the next page. When next_cursor is null, you have reached the last page."
Review checklist
A reviewer can run through these eight questions in about five minutes.
- Can a developer make a first successful call using only this page?
- Does the base URL include the version, and is there a sandbox URL?
- Does the authentication section name the header, the key format and the environment each key works in?
- Does every endpoint say whether it is paginated and whether it is idempotent?
- Are rate limits given as numbers, with the header names and the 429 behavior?
- Does the versioning section define a breaking change and state the notice period before retirement?
- Does each error row say whether a retry is safe, and does that answer match the endpoints table?
- Do the numbers, IDs and codes agree across every section?
Keeping overviews consistent
If you maintain several APIs, or write them for several clients, a fixed template keeps the order and the tables the same. Wordspecs has an API overview template with these fields, and the sample API overview (a fictional parcel-tracking service) shows how it looks. Sheets export to Markdown, PDF and Word.
Related: exporting to Markdown, PDF and Word.