Writing API Documentation
Back in the first section, seven developers displayed a rain chance of 0.82 as "0.82%". The root cause was one missing phrase in Rainkit's reference page: nobody had written down that rain_chance runs from 0 to 1. API documentation is where small omissions turn into hundreds of support questions, and where a clear page quietly prevents them.
The rule
Document every endpoint: what it does, how to call it, what comes back, what breaks.
A reference entry for one endpoint answers the same questions in the same order, every time.
1. What it does. One sentence: "Returns hourly rain forecasts for a location, up to 24 hours ahead."
2. How to call it. The method and path, GET /v1/forecast, how to authenticate, and a parameter table:
| Name | Type | Required | Description |
|---|---|---|---|
lat |
number | yes | Latitude of the location, in decimal degrees |
lon |
number | yes | Longitude of the location, in decimal degrees |
hours |
integer | no | How many hours ahead, from 1 to 24. Default 6 |
3. What comes back. A full example response, plus a description of every field, including units and ranges: "rain_chance: a number from 0 to 1. Multiply by 100 for a percentage."
4. What breaks. Each error the endpoint can return, why it happens, and how to fix it:
| Status | Cause | Fix |
|---|---|---|
400 invalid_parameter |
"hours must be between 1 and 24" | Send a value from 1 to 24 |
401 unauthorized |
Missing or invalid API key | Send Authorization: Bearer <key> |
429 rate_limited |
Daily limit reached | Wait for the Retry-After time, or cache results |
Show the example request in every language you support, usually curl plus each SDK, and keep the examples identical in what they do. Beside the reference, a short quickstart is the front door: the fastest route from sign-up to one successful call.
The shortcut
Use the copy-paste test: open a fresh terminal, paste each example exactly as written (swapping in only your own key), and check that you get the response the page shows. Anything you had to fix silently is a bug in the docs.
What it does
"Returns hourly rain forecasts for a location, up to 24 hours ahead."
Drills
Answer fast — trust the rule.
What should a parameter table row for hours include?
Why include a full example response, not just a list of fields?
When is the error section for 400 invalid_parameter most useful?
Meera pastes a docs example into a fresh terminal, and it fails until she adds a missing header. What does this mean?
Remember
- Document every endpoint: what it does, how to call it, what comes back, what breaks.
- Shortcut: the copy-paste test, in a fresh terminal, for every example.
- Trap: examples nobody reran after the API changed, and error sections that say only "Bad request".