API design

Step 3 of the method from lesson 01: requirements → estimate → API → data model → … Before you argue about boxes, write down what the system actually does as a list of concrete operations. That list is the contract — the promise clients code against. It outlives every implementation behind it, and it is the most expensive thing in the system to change once anyone depends on it.

Why design the API before the boxes

A newcomer's instinct is to start drawing servers and databases. But you cannot size a database for an operation you haven't named, and you cannot reason about latency (02) without knowing how many round trips a user action takes. Writing the API first does three things:

• It pins down scope. "Build Twitter" is a mood; POST /tweets, GET /users/{id}/timeline?cursor=…, POST /tweets/{id}/likes is a system. The verbs are the requirements, made testable.
• It exposes the hard parts. The moment you write GET /timeline you must ask "how is this paginated, how fresh, how big?" — questions that drive the data model and caching decisions that follow.
• It is the thing you can't take back. Internals are reversible; a shipped contract is not. Treat its design with the seriousness of the one decision you'll be living with in two years.

In an interview, sketching 4–6 endpoints right after the estimate signals seniority: it shows you reason from what the system promises down to how it keeps the promise, not the reverse.

REST & resource modelling: the contract is the vocabulary

REST (representational state transfer) is less a protocol than a discipline: model your domain as resources — nouns with stable URLs — and act on them with a small fixed set of HTTP verbs. The power is that the verbs and the response codes are a vocabulary every client, proxy and cache already understands. You are not inventing a language; you are reusing HTTP's.

Safe means "no observable side effect" (a GET must never mutate state — caches and crawlers rely on this). Idempotent means "doing it twice lands you in the same final state as doing it once" — the property the whole reliability story below hangs on. Resources are nouns; resist verbs in URLs (POST /createPhoto is a smell — the verb belongs in the method, not the path).

The status code IS the contract

Clients branch on status codes, so a sloppy or inconsistent code is a broken contract. Learn the vocabulary as three families — 2xx "it worked", 4xx "you messed up, don't retry unchanged", 5xx "I messed up, retry may help":

The 4xx/5xx split is load-bearing for reliability: a client (and its retry library) should retry 5xx and 429 but never blindly retry a 400 or 422 — the request is wrong and will stay wrong. The 400-vs-422 and 401-vs-403 distinctions are exactly the kind of precision an interviewer probes for.

REST vs gRPC vs GraphQL — pick by who's calling

These are three answers to "how do client and server talk", and the right one depends almost entirely on who the client is: a public third-party developer, a browser/mobile app, or another one of your own services. Each buys something real and bills you for it elsewhere.

The honest one-liner: REST for public and simple, gRPC for internal and fast, GraphQL for rich front-ends fetching graphs. Plenty of real systems run all three — gRPC between services, a REST or GraphQL gateway at the edge. Notice the recurring tension: GraphQL trades the client's round trips for the server's resolver complexity and lost edge caching. That round-trip cost is exactly what the widget below makes concrete.

Idempotency as a contract: assume duplicates, always

Here is a scenario you will hit. A client POSTs "charge $50", the charge succeeds, but the response is lost to a flaky network. The client times out and — reasonably — retries. Without protection, you've now charged $100. This is not an edge case: clients retry, load balancers (05) re-dispatch, and fault-tolerance layers (13) replay. Duplicates are the normal case at scale, not the exception.

Some verbs are safe by construction (re-read the table): GET, PUT and DELETE are idempotent — replaying them lands in the same state. POST is not, because each call means "make a new one." So for unsafe creates you make idempotency an explicit term of the contract via the Idempotency-Key header (the pattern Stripe popularised):

The client generates a unique key per logical operation (a UUID) and resends the same key on retry. The server records "key → outcome" for a dedup window (e.g. 24h) and, on a repeat, returns the stored result without re-executing. Buys: safe retries, so the network can fail freely. Costs: a storage layer keyed by idempotency key, a TTL to bound its growth, and a subtle decision about what counts as "the same request" (same key + different body should arguably be a 422). The deeper version of this — making the side effect itself exactly-once across services — is the subject of 12.

Pagination: never return an unbounded list

A collection endpoint that returns "all the things" is a latency and memory time-bomb the day the collection grows. Every list endpoint must be paginated and must cap the page size (a client asking for limit=10000000 gets clamped, not obeyed). The interesting choice is how you page:

The default for any feed, log, or large list is cursor pagination: it is the only scheme that stays correct when the underlying list mutates (which feeds always do) and the only one whose cost doesn't grow as users page deeper. Offset is fine for small, mostly-static admin tables where "go to page 7" matters. This ties directly to 07: in a sharded system, offset pagination is nearly unworkable (offset across shards is meaningless), whereas a sort-key cursor merges cleanly across partitions.

Versioning & evolution: change without breaking callers

The contract will need to change, but clients upgrade on their schedule, not yours. The whole game of versioning is shipping change while old clients keep working. First, classify the change:

• Backward-compatible (additive): adding a new optional field, a new endpoint, a new optional parameter, a new enum value clients can ignore. Safe — ship it without a version bump.
• Breaking: removing/renaming a field, changing a type, making an optional field required, changing status-code semantics. This needs a new version, because it will crash existing clients.

How you expose the version is a trade:

URI versioning wins in practice for public APIs on sheer legibility. Whatever you pick, lean on the tolerant reader principle: clients should ignore fields they don't recognise rather than reject the whole payload — that single discipline turns most additive changes into non-events. And version with a deprecation plan: announce, set a sunset date, emit a Deprecation/Sunset header, then retire. A version you can never delete is a maintenance tax forever.

Error contracts: machine-readable, and never leaking internals

Errors are part of the contract too, and "return a 500 with a stack trace" fails twice: it gives clients nothing to branch on, and it leaks your internals (table names, file paths) to the world. Return a consistent, machine-readable error envelope — the application/problem+json shape (RFC 7807) is a fine default:

HTTP/1.1 409 Conflict
Content-Type: application/problem+json

{
  "type":   "https://api.acme.com/errors/duplicate-email",
  "title":  "Email already registered",
  "status": 409,
  "detail": "An account with this email already exists.",
  "code":   "EMAIL_TAKEN",            // STABLE, client branches on this
  "request_id": "req_8f3a..."          // for support / tracing
}

The keys that matter: a stable machine code (EMAIL_TAKEN) clients can switch on without string-matching the human title (which you must be free to reword); the numeric status mirroring the HTTP code; a human detail; and a request_id so a user can quote it to support and you can find the trace. Buys: clients handle errors deterministically; you can change wording freely. Costs: the discipline of maintaining a stable error-code registry — but never, ever surface raw exceptions, SQL, or internal hostnames; those are a security and coupling leak.

Async & long-running APIs: don't hold the connection open

Some operations — video transcoding, a bulk import, a report — take seconds to minutes. Blocking the HTTP request until they finish ties up a connection, courts client timeouts, and falls apart on retry. The pattern is to make the work asynchronous at the contract level: accept it, hand back a handle, let the client check on it.

This is the 202 Accepted → job id → poll a status endpoint (or receive a webhook) pattern. 202 means "I've accepted the work, it isn't done yet"; the job id is the handle; the client either polls GET /jobs/{id} until done/failed or registers a webhook for push notification. Buys: short, reliable requests; work that survives a slow backend; natural fit for the queue in 11. Costs: more moving parts (a job store, status semantics, webhook retry/verification), and the client must handle "not done yet." Combine with the idempotency key so a retried submit doesn't enqueue the job twice — the exactly-once-across-services concern of 12.

Batch / bulk endpoints: spend one round trip instead of N

The flip side of chattiness: if a client routinely needs 50 related items, making it issue 50 GETs is a round-trip tax (each costs an RTT — recall 02). Offer a batch endpoint — POST /photos/batchGet with a list of ids, or GET /photos?ids=1,2,3 — that returns many in one call. Buys: collapses N round trips to one or two; this is one of the cheapest latency wins there is (more in 14). Costs: partial-failure semantics (what if item 3 of 50 fails? — usually a per-item result array with individual statuses, not a single all-or-nothing code) and a cap on batch size to bound the work. The calculator below quantifies exactly how big this win is.

Try it: round-trip & over-fetch calculator

The single most common API-design mistake a newcomer ships is the chatty 1 + N pattern: fetch a list, then loop and fetch each child one at a time. Each call costs a full round trip, and done serially they add up. Move the sliders and watch how a batch endpoint or a single GraphQL query collapses the wall-clock latency.

Interview prompts you should be ready for