API Reference Writing
Reference vs. guide docs, code examples, error docs, versioning, and pagination
API reference writing essentials
- Reference vs. guide: reference = complete spec; guide = how to achieve a goal — both needed
- Code examples: complete, copy-paste-ready with auth header and realistic parameters
- Error docs: API-specific error codes + message format + cause + handling guidance
- Versioning: scheme + active versions + deprecation timeline + migration guide
- Pagination: default + max + parameters + response metadata (total_count, has_next_page) + example
Question 0 of 5
What is the difference between API reference documentation and API guide documentation?
Reference = complete spec; Guide = how to achieve a goal. When to use each:
- Reference docs: "What does GET /users/{id} return?" — exhaustive, lookup-optimised. Developers consult reference when they know what they want to do and need exact parameter names or response fields.
- Guide docs (tutorials/how-tos): "How do I implement OAuth2 login?" — narrative, task-optimised. Developers follow guides when learning a new API area.
- Reference generated from OpenAPI spec (Swagger UI, Redoc)
- Guides hand-written — they show the happy path in context, not just the spec
Which API code example is most useful in reference documentation?
Complete, copy-paste-ready example with auth header and all required parameters. API code example checklist:
- ✅ Full URL with realistic query parameters
- ✅ Required headers (Authorization, Content-Type)
- ✅ Realistic placeholder values (YOUR_API_TOKEN, not {token})
- ✅ Multi-line formatting for readability (backslash continuation)
- ✅ Can be copy-pasted and run with only substituting the token
What should an API error response documentation section contain?
API-specific error codes + message format + cause + handling guidance. Error documentation template:
- Error format: all errors return
{"error": "error_code", "message": "human-readable message", "request_id": "req_abc123"} - Error code table:
invalid_api_key— 401 — The API key is missing, malformed, or revoked. Check key in dashboard.rate_limit_exceeded— 429 — Exceeded 1,000 requests/minute. Implement exponential backoff with Retry-After header.resource_not_found— 404 — The requested resource does not exist. Verify the ID.validation_error— 422 — Request body contains invalid values. See "errors" array in response for field-level details.
What is "API versioning" and how should it be documented?
Versioning scheme + active versions + deprecation timeline + migration guide. API versioning documentation:
- Versioning scheme: "This API uses URL versioning: /v1/, /v2/. Breaking changes always get a new version. Non-breaking changes (added fields, new endpoints) are added to the current version."
- Active versions: "v2 (current), v1 (deprecated — end of life: 2027-01-01)"
- Deprecation policy: "We support each version for 18 months after deprecation. You'll receive email notice 6 months before end of life."
- Migration guide: "v1 → v2 changes: the user object now uses snake_case (firstName → first_name). See the migration guide."
Which pagination documentation is most complete?
Default page size + max + parameter description + response metadata + example. Complete pagination documentation includes:
- Default: "20 items per page" — developers need to know what they get without parameters
- Max: "max: 100" — tells developers the ceiling before rate limits apply
- Request parameters: page (integer, min: 1), limit (integer, default: 20, max: 100)
- Response metadata: total_count, has_next_page, next_page_token (for cursor-based), total_pages
- Example: shows exactly what the URL looks like and what you get back