API Design Basics
Resources and verbs are the easy half. The other half: which calls are safe to retry, how to paginate data that is changing underneath you, and how to add a field without breaking anyone.
Prerequisites: HTTP methods and JSON.
Cover these firstNetworking & Protocols
After this: Design an endpoint that survives retries, pagination drift, and its own next version.
Suggested first pass: Read sections 1–5, answer each section in your own words, then use the remaining failure modes and exercises as the advanced pass.
A REST-style API names things and acts on them. Paths are nouns, /orders, /orders/123, /orders/123/refunds, and the HTTP method says what you are doing.
Status codes carry more weight than people expect, because clients and infrastructure branch on them.
- 2xx: worked.
- 4xx: the caller is wrong. Do not retry without changing something.
- 5xx: we are wrong. Retrying may work.
- 409 Conflict: the request clashes with current state.
- 429 with
Retry-After: slow down, and here is for how long.
Retry logic, load balancers, monitoring, and generated client libraries all read the status code. A 200 tells every one of them the call succeeded, so failures go unretried, uncounted, and unalerted. This is not a style preference. It is the machine-readable half of your contract.