Reading REST API Docs
HTTP methods, path parameters, query parameters, authentication, rate limits, and error formats
REST API docs vocabulary
- GET/POST/PUT/PATCH/DELETE — read / create / replace / partial-update / delete
- Path parameter {id} — variable in the URL path; query parameter — after ?
- Bearer token — Authorization: Bearer <token> header on every request
- Rate limit — max requests per time window; 429 = too many requests
- Paginated list — data array + meta with total/page/per_page
Question 0 of 5
A REST API doc entry reads: GET /api/v2/users/{id}. How would you describe this endpoint in plain English?
- GET — retrieve/fetch/read (no body, no side effects)
- POST — create a new resource
- PUT — replace a resource entirely
- PATCH — partially update a resource
- DELETE — remove a resource
/api/v2 is the base path with version; /users is the resource collection; /{id} is the path parameter (a variable). When reading: "GET /users/{id}" = "get a single user by id".API docs say: Authentication: Bearer token required. Rate limit: 100 requests/minute. What do these two lines mean for a client developer?
- Bearer token — include in header:
Authorization: Bearer <token> - API key — include as header (
X-API-Key) or query param (?api_key=) - Rate limit — max requests per time window; exceeding returns 429 Too Many Requests
- Quota — total allowed over a longer period (daily/monthly)
Retry-After or X-RateLimit-Reset headers.API docs list this parameter table:page — integer — optional — Page number (default: 1)
per_page — integer — optional — Items per page (max: 100, default: 20)
sort — string — optional — Field to sort by (created_at, name)
How would you request page 3, 50 items, sorted by name?
- query parameters — after the
?, joined with&:?key=value&key2=value2 - path parameters — part of the URL path:
/users/{id} - request body parameters — sent in the body (for POST/PUT/PATCH)
- header parameters — sent in HTTP headers (auth, content-type)
An API reference says: "Returns a paginated list of orders. Each order object contains id, status, total, and a nested customer object." What would you expect in the response JSON?
- "paginated list" → expect pagination metadata (total, page, per_page) alongside the data array
- "each X contains" → fields present on every item in the array
- "nested Y object" → a sub-object within each item, not a separate endpoint call
- "optional field" → may be absent or null in some responses
{ data: [{ id, status, total, customer: { id, name } }], meta: { total, page } }.API docs include a section: Errors: All errors follow the format {"error": {"code": "string", "message": "string", "details": []}}. Common codes: NOT_FOUND, VALIDATION_ERROR, UNAUTHORIZED.
What should a client developer take from this?
- error code — machine-readable string (
NOT_FOUND,RATE_LIMIT_EXCEEDED) — use this in switch/if logic - message — human-readable; good for logging and displaying to developers, not always to end users
- details array — field-level validation errors:
[{field: "email", issue: "invalid format"}]