Reading: API Documentation
3 exercises — read realistic REST API documentation and HTTP status code references. Extract parameters, understand response codes, and interpret technical specifications.
How to read API documentation efficiently
- Endpoint line — method + path is always at the top:
GET /users/{id} - Required vs optional — always check whether parameters are mandatory
- Response codes — scan this section when debugging; each code has a specific cause
- Examples — sample values show the expected format for inputs and outputs
- Rate limits — check this before building polling or batch logic
0 / 3 completed
1 / 3
Passage: GET /users/{id} API Documentation
GET /users/{id}
Returns the profile of a single user by their unique identifier.
Path Parameters
id (string, required) The unique identifier of the user. Must be a valid UUID v4.
Query Parameters
fields (string, optional) Comma-separated list of fields to return.
Default: all fields. Example: fields=name,email,role
include_deleted (boolean, optional) If true, returns the user even if their
account has been soft-deleted. Default: false.
Request Headers
Authorization (required) Bearer token. Format: "Bearer <access_token>"
Accept (optional) Response format. Supported: application/json (default),
application/xml
Response Codes
200 OK User found and returned successfully
400 Bad Request The id parameter is not a valid UUID
401 Unauthorized Missing or invalid Authorization header
403 Forbidden Authenticated user does not have permission to view this user
404 Not Found No user exists with the given id (or account deleted and
include_deleted=false)
Response Body (200)
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Alice Johnson",
"email": "alice@example.com",
"role": "admin",
"created_at": "2024-01-15T09:30:00Z",
"deleted_at": null
}
Rate Limiting
This endpoint is rate-limited to 100 requests per minute per API key.
Exceeding the limit returns HTTP 429 Too Many Requests with a Retry-After header. A developer calls
GET /users/123 and receives a 400 Bad Request response. What is the most likely cause according to the documentation?400 Bad Request — invalid UUID:
The documentation explicitly states under Response Codes:
"400 Bad Request — The id parameter is not a valid UUID"
The value "123" is not a UUID v4. A valid UUID looks like:
Why not the other options?
Response codes sections are structured reference material — scan them like a lookup table. When debugging, find the exact code and match it to the documented cause rather than guessing.
The documentation explicitly states under Response Codes:
"400 Bad Request — The id parameter is not a valid UUID"
The value "123" is not a UUID v4. A valid UUID looks like:
550e8400-e29b-41d4-a716-446655440000.Why not the other options?
- 404 (not 400) is returned when the user does not exist
- 401 is returned for missing/invalid Authorization header
- 429 is returned when the rate limit is exceeded
Response codes sections are structured reference material — scan them like a lookup table. When debugging, find the exact code and match it to the documented cause rather than guessing.