Document an API Endpoint with a Runnable Example
API docs are read by someone writing a client under deadline. Give them a request they can paste into curl and the exact response, then the errors.
Procedure
- Open with the method and path in a code span:
POST /v1/invoices. State the purpose in one sentence.
- Give an auth line: required scopes and header, e.g.
Authorization: Bearer $ACME_TOKEN, scope invoices:write.
- List path, query, and body parameters in a table with name, type, required, and default. Mark enum values exhaustively: status in {draft, open, paid, void}.
- Provide a runnable curl example with real-looking values and the token in a variable so the reader substitutes one thing:
curl -sS -X POST https://api.acme.dev/v1/invoices -H "Authorization: Bearer $ACME_TOKEN" -d '{"amount_cents":500,"currency":"usd"}'
- Show the actual JSON response with a 200, including field types. Do not hand-wave with an empty object.
- Document every error the endpoint can return: code, HTTP status, meaning, and the fix. For 409 conflict_idempotency, tell the caller to reuse the same Idempotency-Key or fetch the existing resource.
- Note rate limits and the
Retry-After header value the endpoint sends.
- State idempotency behaviour explicitly: which key header, and the retention window (e.g. 24h).
- Add one worked error example showing the fix applied.
- Document pagination if the endpoint lists: the cursor field, the page size limit, and the parameter to advance.
- Keep the request and response in a consistent order so a reader scans top-to-bottom.
- Give a timestamp and timezone convention for any date field (
ISO 8601, UTC).
Pitfalls
- A request example that omits the auth header, so the first copy-paste returns 401.
- Showing only the happy path response; callers then mishandle the 4xx cases.
- Parameter tables that mark everything optional when the server rejects missing fields.
- Field descriptions that restate the name, such as "amount: the amount".
- Documenting the success status only, hiding that the same verb returns 202 when queued.
- A pagination note that omits the maximum page size, so callers guess and get truncated results.
- Amounts shown as floats where the field is integer minor units, causing rounding bugs downstream.
Verification
curl -sS -o /dev/null -w '%{http_code}\n' -X POST "$BASE/v1/invoices" -H "Authorization: Bearer $ACME_TOKEN" -d '{}'
# run against staging; the code must match the documented error for that input
Run every documented example against staging and confirm status codes and response shapes match the docs exactly.
1---2name: document-an-api-endpoint-with-a-runnable-example3description: Use when writing reference docs for an HTTP API endpoint. Specifies method, path, parameters, a copy-pasteable request, a real response, and each error with its fix.4metadata:5 source: https://skillmd.com/skills/jiayaoqijia/document-an-api-endpoint-with-a-runnable-example6---78# Document an API Endpoint with a Runnable Example910API docs are read by someone writing a client under deadline. Give them a request they can paste into curl and the exact response, then the errors.1112## Procedure13141. Open with the method and path in a code span: `POST /v1/invoices`. State the purpose in one sentence.152. Give an auth line: required scopes and header, e.g. `Authorization: Bearer $ACME_TOKEN`, scope `invoices:write`.163. List path, query, and body parameters in a table with name, type, required, and default. Mark enum values exhaustively: status in {draft, open, paid, void}.174. Provide a runnable curl example with real-looking values and the token in a variable so the reader substitutes one thing:18 `curl -sS -X POST https://api.acme.dev/v1/invoices -H "Authorization: Bearer $ACME_TOKEN" -d '{"amount_cents":500,"currency":"usd"}'`195. Show the actual JSON response with a 200, including field types. Do not hand-wave with an empty object.206. Document every error the endpoint can return: code, HTTP status, meaning, and the fix. For 409 conflict_idempotency, tell the caller to reuse the same Idempotency-Key or fetch the existing resource.217. Note rate limits and the `Retry-After` header value the endpoint sends.228. State idempotency behaviour explicitly: which key header, and the retention window (e.g. 24h).239. Add one worked error example showing the fix applied.2410. Document pagination if the endpoint lists: the cursor field, the page size limit, and the parameter to advance.2511. Keep the request and response in a consistent order so a reader scans top-to-bottom.2612. Give a timestamp and timezone convention for any date field (`ISO 8601, UTC`).2728## Pitfalls2930- A request example that omits the auth header, so the first copy-paste returns 401.31- Showing only the happy path response; callers then mishandle the 4xx cases.32- Parameter tables that mark everything optional when the server rejects missing fields.33- Field descriptions that restate the name, such as "amount: the amount".34- Documenting the success status only, hiding that the same verb returns 202 when queued.35- A pagination note that omits the maximum page size, so callers guess and get truncated results.36- Amounts shown as floats where the field is integer minor units, causing rounding bugs downstream.3738## Verification3940 curl -sS -o /dev/null -w '%{http_code}\n' -X POST "$BASE/v1/invoices" -H "Authorization: Bearer $ACME_TOKEN" -d '{}'41 # run against staging; the code must match the documented error for that input4243Run every documented example against staging and confirm status codes and response shapes match the docs exactly.