Practice & Assessment
Test your understanding of API Reference Documentation
Multiple Choice Questions
6A developer reports they keep getting 400 errors from your API but can't find the cause in the docs. What is most likely missing from your API reference?
What is the difference between a null response field and an absent response field?
Why should authentication documentation include the exact header format rather than just naming the auth type?
What rate limiting headers should be documented in your API reference?
A code example uses 'user_id': 'abc123' as sample data. What is wrong with this?
What is the correct placement for rate limiting information in API documentation?
Coding Challenges
1Document a REST API Endpoint from a Specification
You are given a plain-language specification for a PATCH /api/v1/posts/{id} endpoint that updates a blog post. The spec describes: 3 path parameters, 5 optional body fields (each with type, max length, and validation rules), 3 possible success responses (200, 204), and 4 error codes. Task: write complete API reference documentation in Markdown including: method and path, one-line description, authentication note, parameter table, request body schema with all constraints, all response scenarios with example JSON, and a complete error code table. Include one curl example and one JavaScript fetch example with realistic test data. Output: Markdown file. Estimated time: 25–30 minutes.
Mini Project
Full API Reference for a Todo REST API
Write complete API reference documentation for a fictional Todo REST API with 6 endpoints: GET /todos, POST /todos, GET /todos/{id}, PATCH /todos/{id}, DELETE /todos/{id}, and GET /users/{id}/todos. For each endpoint: method and path, description, authentication requirement, full parameter tables, request body schemas, all response codes and schemas, error code tables with fixes. Include a top-level authentication section with API key setup, Bearer token header format, rate limit headers, and scope table. Provide curl and JavaScript examples for at least 3 endpoints. Deliver as a structured Markdown file with a navigable table of contents.