Design Method & StylesChapter 16 · Draw it
API design
API design
The API is the contract between clients and your system, and in an interview it's where the requirements become concrete — one or two endpoints per functional requirement, named by resource and HTTP method, with the request and response shapes, how lists page, and which writes a client may safely retry. Five or six lines are enough; they fix what the data model has to serve.
- Use when
- Right after the estimate — one or two endpoints per functional requirement · Any list that can grow — page it from the start · Any create, upload or payment-like write that a client may retry
- Avoid when
- Spending a third of the interview on field names and status codes — sketch it, then move on · Versioning schemes or hypermedia detail nobody asked about
- Trade-offs
- Cursor paging stays fast and stable on a big, changing list but can't jump to page 500; offset paging can, and pays by scanning every skipped row · Idempotency keys make retries safe, at the cost of storing each key for a while · A 202 with a status endpoint keeps requests short for long work, and makes the client poll for the result · REST is widely understood and plays well with HTTP caches; RPC frameworks like gRPC give typed calls and streaming, mostly between services
- Requires
- Back-of-the-envelope estimates
3 objectives · 5 misconceptions
- explain Explain how resources (nouns) and standard methods turn functional requirements into endpoints, and which HTTP methods a client may repeat safely after a timeout.
- choose Choose cursor or offset paging for a list, and decide which writes need an idempotency key so that a retry can't create a duplicate.
- choose Choose between a plain synchronous response, a 202 Accepted with a status endpoint, and an RPC-style call for an operation, given how long it takes and who calls it.
- Not true: Endpoints should be named after actions — /createAlbum, /addPhotoToAlbum.
- Not true: Any request can be resent safely if the first one timed out.
- Not true: Paging by offset (page=500) works as well as a cursor on a big list that keeps changing.
- Not true: An interview API needs every field, error code and header written out.
- Not true: REST is the only acceptable style; RPC calls and asynchronous endpoints are mistakes.
Practice
No katas practise this yet.