Writing API Docs
Endpoint descriptions, status codes, parameters, authentication, and documentation style
API documentation essentials
- Endpoint: action + required inputs + success response + error cases
- Parameters: name (type, required/optional) — description. Example: "value". Error: what happens if invalid
- Auth: header format + how to get the token + expiry + error code
- Style: present simple, active, no subject — "Creates", "Returns", "Accepts"
- Status codes: 400 = bad syntax, 401 = not authenticated, 403 = not authorised, 409 = conflict, 422 = invalid values
Question 0 of 5
Which API endpoint description is written most clearly?
Action + required inputs + response + error cases is the complete API endpoint description. Good endpoint documentation includes:
- What it does: "Creates a new user account" — one sentence, present tense
- Required inputs: "Requires email and password in the request body"
- Success response: "Returns the created user object with id, email, and created_at"
- Error cases: "Returns 409 if a user with the given email already exists"
Which HTTP status code description is correctly matched?
422 = valid syntax, invalid semantics. HTTP status code reference for API docs:
- 200 OK: success — request processed, response body contains result
- 201 Created: resource successfully created (use after POST that creates)
- 400 Bad Request: malformed request — syntax error, missing required field
- 401 Unauthorized: authentication required or token invalid
- 403 Forbidden: authenticated but not authorised for this resource
- 404 Not Found: resource does not exist
- 409 Conflict: resource already exists (duplicate email, unique constraint)
- 422 Unprocessable Entity: valid JSON but invalid field values
- 500 Internal Server Error: unexpected server failure
When documenting a request parameter, which format is most complete?
Name + type + required/optional + description + example + error behaviour is the complete parameter documentation. Parameter documentation template:
name(type, required|optional) — Description. Example: "value". Error: what happens if invalid.
page(integer, optional, default: 1) — Page number for paginated results. Must be ≥ 1. Example: 3. Returns 400 if not a positive integer.limit(integer, optional, default: 20, max: 100) — Number of results per page. Returns 400 if > 100.
A team is documenting authentication for their API. Which approach is clearest?
Header format + how to get the token + expiry + error code is complete auth documentation. Authentication documentation checklist:
- ✅ Header name and format:
Authorization: Bearer <token> - ✅ How to obtain: "via POST /auth/token" — not assumed knowledge
- ✅ Token lifecycle: "expire after 24 hours" — prevents "why did my integration break?"
- ✅ Error response: "Returns 401" — developers know what to handle
Which is the correct tense and voice for API documentation?
Present simple, active voice, no subject is the API docs convention. API documentation style guide:
- ✅ Present simple, no subject: "Creates", "Returns", "Accepts", "Requires", "Deletes"
- ❌ Past tense: "was created to" — describes history, not current behaviour
- ❌ Future tense: "will create" — API docs describe current behaviour, not predictions
- ❌ Second person instruction: "The developer should send" — this is tutorial style, not reference style