API Design

Start here: the client you can't take back#

You ship an API. A mobile app integrates against it, then a partner's backend, then a script someone wrote two years ago and forgot. None of that code is yours. You can't step through it, you can't redeploy it, and you often can't even contact whoever wrote it. Whatever your API did on the day they integrated is what their code now depends on.

That's what makes API design different from designing a function. A function has one caller — you — and you can change both sides at once. An API has callers you'll never meet, and they only ever see the edge: the URLs, the request and response shapes, the status codes, the headers. Get that edge wrong and you either break clients or freeze the design forever. The whole job is to shape that edge so it survives change, retries, and scale without either breaking the client or trapping you.

Model resources, then pick the verb#

The first decision is how to name things. The style most web APIs follow is REST, which has one central idea: the things your API exposes are resources — nouns with a stable address. A user is a resource at `/users/42`. That user's orders are a resource at `/users/42/orders`. You don't invent a verb-shaped URL like `/getUserOrders`; the noun is the URL, and what you do to it is the HTTP method.

That split — noun in the path, verb in the method — is what makes a REST API predictable. A client that has never read your docs can still guess that `GET /users/42` reads user 42 and `DELETE /users/42` removes it, because the meaning lives in the method, and the methods are the same for every resource. The verbs are a small, fixed vocabulary defined by HTTP itself.

Two properties of those verbs decide how clients can treat them, and they're the ones interviewers reach for. A method is safe if calling it changes nothing on the server — a pure read. A method is idempotent if making the same call twice has the same effect as making it once. Safe implies idempotent (a read changes nothing, so any number of reads is the same as one), but not the reverse: deleting a resource changes the server, yet deleting it twice lands in the same final state as deleting it once, so DELETE is idempotent without being safe.

Here's the table every client relies on, defined by the HTTP spec (RFC 9110). It's worth knowing cold, because it's what tells a client whether a timed-out request is safe to retry.

Read the POST row carefully, because it's the source of a whole topic. POST is neither safe nor idempotent: `POST /charges` creates a new charge every time it runs. So if a client sends a charge, times out, and retries, a naive server charges the card twice. That's not a REST detail — it's the exact problem the Idempotency & Retries topic (/idempotency) solves, and it's why a money-moving POST carries a client-chosen idempotency key that lets the server recognize the retry and reply with the original result instead of charging again. The verb table is where you first see that a POST is the dangerous one.

Pagination that survives a moving dataset#

No client wants a million rows in one response, so a list endpoint returns a page at a time. The obvious way is offset/limit: `GET /events?limit=20&offset=40` means "skip 40 rows, give me the next 20." It's easy to build and it works fine on a small, still dataset. It breaks in two ways once the dataset is large and changing.

The first break is speed. To answer `offset=1000000&limit=20`, the database can't jump straight to row 1,000,000 — it has to walk through and discard the first million rows to reach the ones you want. The cost of a page grows with how deep you are, so the last pages of a big list get slower and slower. Fetching page one is cheap; fetching page fifty-thousand scans a million rows to hand back twenty.

The second break is correctness, and it's the subtle one. Offset counts positions, but positions shift when rows are inserted or deleted. Say a reader pulls page one (rows 1–20), and before they ask for page two, someone inserts a new row at the top. Every row shifts down by one. Now `offset=20` points at the row that used to be at position 20 — the reader already saw it, so it appears again as a duplicate. Delete a row instead and the opposite happens: everything shifts up, `offset=20` skips over a row the reader never sees. On a busy feed with constant writes, offset pagination silently skips and duplicates rows.

The fix is cursor pagination (also called keyset pagination). Instead of "skip N rows," the client says "give me the rows after this specific one." The cursor names a position by the value of the row it left off at — for a feed sorted newest-first, that's the last row's sort key. The next page is a query like `WHERE (created_at, id) < (last_seen_created_at, last_seen_id) ORDER BY created_at DESC, id DESC LIMIT 20`.

Two things fall out of this. Because the query filters on an indexed column instead of counting rows, every page costs the same whether you're on page one or page fifty-thousand — the database seeks to the cursor's position and reads twenty rows. And because the anchor is a row's own value, not a moving count, inserting or deleting rows elsewhere can't shift what comes after the cursor, so no skips and no duplicates. Cursor pagination fixes both offset breaks at once.

Errors clients can act on#

Half of what a client's code does is handle the request that didn't work. So the error path is part of the contract, not an afterthought. Two rules make errors usable: use the HTTP status code the way it's meant, and put a machine-readable reason in the body.

The status code is the coarse signal, and clients branch on its class. The 2xx range means success. The 4xx range means the client's request was wrong — 400 for a malformed request, 401 for "you're not authenticated," 403 for "authenticated but not allowed," 404 for "no such resource," 429 for "you're being rate-limited." The 5xx range means the server broke — 500 for an unexpected failure, 503 for "temporarily unavailable." The line between 4xx and 5xx is the one that matters most: a 4xx is the client's fault and retrying the same request won't help, while a 5xx is the server's fault and might succeed on retry. Return the wrong class and clients either retry things that will never work or give up on things that would have.

The status code alone is too coarse, though. A 400 tells the client "bad request" but not which field, or which of a dozen validation rules failed. So a well-designed API also returns a structured error body with a stable, machine-readable code. Stripe's shape is the canonical one: a `type`, a short string `code` like `card_declined`, a human-readable `message`, and often the specific `param` that was wrong.

HTTP/1.1 402 Payment Required

{
  "error": {
    "type":    "card_error",
    "code":    "card_declined",   // stable — branch on this in code
    "param":   "card_number",     // which field was wrong
    "message": "Your card was declined."  // for humans, may change
  }
}

The split is the whole point. The `message` is for a human reading a log, and you're free to reword it. The `code` is for the client's code — `if (err.code === "card_declined") retryWithNewCard()` — and it must stay stable forever, because that string is now part of the contract. Never make a client parse the human message to figure out what happened; give it a code to branch on. (There's even a standard envelope for this, RFC 9457 "Problem Details," a JSON shape with `type`, `title`, `status`, and `detail` fields, for teams that want an off-the-shelf format instead of inventing their own.)

Two more headers are part of the contract, not extras. Authentication travels on every request — usually `Authorization: Bearer <token>` — because a REST API is stateless and remembers no login between calls. And rate limiting is communicated in the response: a 429 status when you've sent too many requests, plus headers like `RateLimit-Remaining` and `Retry-After` telling a well-behaved client how much it has left and when to try again. The rate-limiting mechanism that decides all this — token buckets, sliding windows — has its own simulator (/ratelimit/sim); from the API's side, the job is just to surface the limit in a way clients can obey.

Versioning: the bill you pay later#

Eventually you have to change the API in a way that would break existing clients — rename a field, drop one, change a type. You can't just do it, because the clients you don't control are still sending the old shape. Versioning is how you ship the new design while the old one keeps working. There are three common places to put the version.

URL versioning (`/v1/`, `/v2/`) is the most common because it's the most obvious — you can see the version, curl it, and route on it. Header and media-type versioning keep URLs clean but hide the version somewhere easier to get wrong. There's no universally right choice; the point is to pick one deliberately and be consistent, because clients hard-code whatever you chose.

That's the discipline behind the honest interview answer: design for backward compatibility so most changes are additive and free, and treat a version bump as the expensive, last-resort option — because each live version is one more thing you'll maintain long after you've forgotten why. Some APIs (Stripe among them) go further and pin each client to the version that was current when they signed up, translating internally, so a client never has to migrate at all — trading heavy internal complexity for a promise that nothing breaks.