API Design

1. 1 Thinking in resources: what REST actually is REST is constraints, not JSON over HTTP: address resources, let methods decide the action, send hypermedia links to what's next and more. Answers 4 questions 20 steps Start →
2. 2 HTTP methods: what each verb promises A method's promise about safety and idempotency decides when a retry is safe, when a cache is legal, and PUT versus POST. Answers 3 questions 23 steps Start →
3. 3 Status codes and error design: how an API says NO The status code tells machines whose fault the failure was and whether to retry. The error body tells a developer what to fix, and it is never an apology. Answers 3 questions 21 steps Start →
4. 4 Authentication: proving who is calling Authentication asks who you are and authorization asks what you may do. Authentication methods differ mainly in where the identity state lives. Answers 4 questions 23 steps Start →
5. 5 Authorization: a route check is not an object check A role check at the route is needed but not enough. The most common API breach is never asking whether this user owns object 123. Pro Answers 3 questions 13 steps Unlock →
6. 6 The browser enforces CORS, not your server The browser runs the same-origin policy to protect its users. And CORS headers tell the browser which origins may read the reply, but requests from curl, POSTMAN don't go through that check. Answers 3 questions 15 steps Start →
7. 7 API security: three families of mistakes, not a top ten list Real breaches come from missing checks, leaked fields and trusted input. Answers 4 questions 20 steps Start →
8. 8 Designing a list endpoint is designing a small query language Pagination, filtering, sorting and field selection are one problem. Offset paging drifts and slows down. A cursor pins your position to a stable key. Pro Answers 2 questions 20 steps Unlock →
9. 9 HTTP caching: infrastructure you do not own, working for you Declare freshness with Cache-Control and identity with ETag, and caches serve your traffic. The hard part is invalidation. Answers 3 questions 21 steps Start →
10. 10 Conditional requests: the lost update and the fix HTTP already has Two clients read one row and both write it back, and the slower write silently erases the faster one. If-Match makes that loss a loud 412. Pro Answers 1 question Unlock →
11. 11 Rate limiting shares capacity fairly, and the algorithm decides how A limiter protects a shared resource from any one caller, malicious or just retrying badly. The algorithm decides which bursts get through. Answers 5 questions 19 steps Start →
12. 12 Versioning an API: changing the contract you already published Only a breaking change needs a new version, and most changes are additive. The deprecation lifecycle matters far more than where the version number goes. Answers 7 questions 20 steps Start →
13. 13 Async APIs and webhooks: when the work takes longer than the request Do not keep the connection open. Return 202 with a job the client can poll, or send a webhook to whoever needs to know and handle every delivery problem. Answers 6 questions 19 steps Start →
14. 14 Real-time APIs: step up from polling only for a clear reason Poll while the delay is acceptable. Push with SSE when only the server has new data, and open a WebSocket only when the client sends messages back. Pro Answers 2 questions 20 steps Unlock →
15. 15 File uploads: do the bytes go through your API or skip it? Every upload design makes one choice: the bytes go through your API or skip it. A signed URL gives permission to upload, but your API still keeps control. Pro Answers 2 questions 18 steps Unlock →
16. 16 Who controls the response shape In REST the server decides the response shape, in GraphQL the client builds it, and in gRPC a compiled contract sets it. The trade-offs come from who decides the shape. Answers 4 questions 19 steps Start →
17. 17 The API gateway: what belongs at the edge A gateway exists so auth, rate limiting, routing and TLS are implemented once at the edge rather than copied into every service. Pro Answers 3 questions 17 steps Unlock →
18. 18 Scale and availability: what statelessness makes possible, and what still fails Holding no session is what lets the servers scale out. For availability, the other half, assume parts fail and stop one failure from spreading. Answers 4 questions 22 steps Start →
19. 19 Service boundaries: chains, events, and sagas Every call you add multiplies the risk. Events decouple services but data agrees later, and a saga replaces a transaction with compensations that undo earlier steps. Pro Answers 4 questions 21 steps Unlock →
20. 20 Testing APIs: three different questions Three suites, three questions: behaviour, compatibility, capacity. The contract test is the one only an API needs. Answers 4 questions 19 steps Start →
21. 21 Documentation: the docs come from the spec, not a hand-written copy Hand-written docs are a second copy of what the code does, and copies go out of date. A spec that generates the reference, clients and checks cannot go out of date. Answers 3 questions 19 steps Start →
22. 22 Observability: percentiles, one request id, and the signal that changes first An average describes a request nobody made. A percentile describes real requests, one request id builds the trace, and saturation is the first signal to change. Pro Answers 4 questions 25 steps Unlock →

← All concepts