REST API design

Resources, methods, status codes, errors, pagination, caching, versioning and auth — the HTTP decisions every backend interview probes, each one modelled as code you can run.

Start the course Practise this with real questions

In this course

Resources and URIsA URI names a thing, the method says what to do with it. Nouns, collections and items, nesting only for real containment, and actions that are not CRUD.8 min
HTTP methods, safety and idempotencyWhat GET, POST, PUT, PATCH and DELETE promise, which are safe and which are idempotent, and why PUT with half a body deletes the other half.10 min
Retries and idempotency keysWhen a client may retry a failed request, and how an idempotency key lets a POST be retried without charging the customer twice.10 min
Status codes, class by classThe five classes, the success and redirect codes an API actually uses, and why 307 and 308 exist when 301 and 302 already did.9 min
Choosing the right 4xx400 or 422, 404 or 405, 409 or 412, and the order an API checks a request in — which decides which error a broken request actually gets.11 min
Designing requests and responsesIds as strings, money in minor units, timestamps in UTC, an explicit allowlist of public fields, and a Location header that resolves where you think it does.10 min
Error responses with problem detailsOne error format for the whole API — RFC 9457 problem details — what each member means, how to report several invalid fields, and what never belongs in an error body.10 min
Offset and cursor paginationWhy page 2 of an offset-paged list can repeat or skip items, how keyset cursors avoid it, and the tie-breaker every cursor needs.11 min
Filtering, sorting and paging linksQuery parameters for filters and sort order, why an unknown parameter should be an error, and Link headers that tell the client where the next page is.9 min
HTTP caching and Cache-ControlFresh versus stale, private versus shared caches, what no-cache really means, and the directives that keep one user's data out of a CDN.10 min
ETags, conditional requests and lost updatesIf-None-Match saves bandwidth with 304, If-Match stops two clients overwriting each other with 412, and the strong and weak comparisons that decide both.12 min
Versioning without breaking clientsWhat counts as a breaking change, why tolerant readers make most changes safe, and the trade-offs between path, header and date-based versions.10 min
Authentication, authorization, 401 and 403Who is calling versus what they may do, bearer tokens and their challenges, scopes, token lifetimes, and the object-level check that most API breaches skip.12 min
Rate limiting, 429 and Retry-AfterFixed windows, sliding windows and token buckets, the double burst at a window boundary, and how to tell a client exactly when to come back.11 min
OpenAPI and documentationAn API contract as a machine-readable document — what goes in it, design-first versus code-first, and the checks that keep the document and the API honest.10 min
REST, GraphQL and gRPCThree ways to shape an API — resources over HTTP, a typed query language, and generated RPC over HTTP/2 — and the trade-offs that decide between them.11 min