Most API questions are not really about REST. They are about what happens when the network fails halfway through, when the client retries, when the data set grows past what a single response can carry, and when you need to change the shape of something that other teams already depend on.

This note is organised around those failure modes rather than around a style guide.

Safe, idempotent, neither

Three properties, and almost every retry decision follows from them.

• Safe — the request does not change server state. GET, HEAD, OPTIONS.
• Idempotent — sending it N times leaves the same state as sending it once. GET, HEAD, PUT, DELETE, OPTIONS.
• Neither — POST and PATCH.

Safe implies idempotent. The reverse is not true: DELETE /orders/42 changes state, but running it five times leaves the same state as running it once.

This matters because anything not idempotent cannot be safely retried by a client, a proxy, or a load balancer. A timeout does not tell the client whether the request was applied. If the operation is idempotent, the client can just send it again. If it is not, retrying might charge a card twice.

PUT is idempotent because it carries the complete desired state. PATCH usually is not, because it carries a delta — PATCH /accounts/1 {"balance_delta": -10} applied twice removes twenty. A PATCH that carries absolute values ({"status": "cancelled"}) is idempotent in practice, but the method does not promise it, so intermediaries will not assume it.

Status codes that carry information

You do not need all of them. You need the ones whose meaning is load-bearing.

The 400 versus 422 line is the one people argue about. A defensible rule: 400 when you could not parse it, 422 when you parsed it fine and the values violate a business rule. What matters in an interview is that you have a rule and apply it consistently.

The 403 versus 404 line is a security decision. Returning 403 on a resource the caller cannot see confirms that it exists. For tenant-scoped resources, 404 leaks less.

Practice

Idempotency keys

A client-generated key, unique per logical operation, sent on requests that are not naturally idempotent.

POST /payments HTTP/1.1
Idempotency-Key: 7c9e6679-7425-40de-944b-e07fc1f90ae7
Content-Type: application/json
 
{"amount_cents": 4000, "currency": "USD", "order_id": 812}

The server side, in one transaction:

CREATE TABLE idempotency_keys (
  key             text PRIMARY KEY,
  request_hash    text NOT NULL,
  response_status int,
  response_body   jsonb,
  created_at      timestamptz NOT NULL DEFAULT now()
);

1. INSERT the key. If it violates the primary key, this is a replay — read the stored response and return it.
2. If the insert succeeded, do the work.
3. Store the status and body against the key before committing.

Three details that separate a real answer from a memorised one:

Store the request hash. If the same key arrives with a different body, that is a client bug, not a retry. Return 422 rather than silently replaying an unrelated response.

Handle the in-flight case. The first request may still be running when the retry arrives. The row exists but has no response yet. Return 409 and let the client retry later — this is the honest answer, and better than blocking a connection.

Expire the keys. They are not permanent records. A 24-hour or 7-day retention window with a cleanup job is normal. Say this out loud; unbounded growth is a real operational cost.

What the key is scoped to

The key identifies one logical attempt. Not one click, and not one session. That distinction is where most implementations leak.

A key generated inside the click handler produces a new key on every click, which is the same as having no key at all. It has to be created once, when the operation becomes possible, and held for as long as that operation can still be retried.

function CheckoutForm({ cart }) {
  const idempotencyKey = useRef(crypto.randomUUID()).current;
 
  async function pay() {
    await fetch("/payments", {
      method: "POST",
      headers: { "Idempotency-Key": idempotencyKey },
      body: JSON.stringify({ amount_cents: cart.total, order_id: cart.orderId }),
    });
  }
}

Held that way, a double click sends two requests carrying the same key, and the server resolves them with the three steps above: the second one either gets 409 because the first is still in flight, or replays the stored response. Disabling the button is still worth doing, but it is a UX improvement, not the correctness boundary — two tabs, a flaky connection and a backgrounded mobile browser all get past it.

The gap is the reload. A key held in component state dies with the component, so a refresh produces a new key and the server sees a genuinely new payment. Moving it into sessionStorage keyed by the order closes the refresh case, and still loses on a different device or cleared storage.

The structural fix is to stop relying on client-side randomness and anchor the operation to a resource the server created:

1. POST /payment-intents with {"order_id": 812} — deduplicated by a unique constraint on order_id, returns pi_abc.
2. POST /payment-intents/pi_abc/confirm — the URL now names the resource, so the operation is idempotent by construction and needs no header at all.

Client-generated keys protect against network retries. Server-issued identifiers protect against client amnesia — a refresh, a crash, a different device. Payment providers ship both layers, and for the same reason.

Practice

Pagination

Why OFFSET degrades

SELECT * FROM orders ORDER BY created_at DESC LIMIT 20 OFFSET 10000;

The database cannot jump to row 10,000. It reads 10,020 rows in sort order and discards 10,000 of them. Page 1 is instant, page 500 is a table scan. Cost grows linearly with page number, which means your slowest queries are the ones nobody looks at — until a crawler, an export job, or a bored user walks the whole list.

There is a correctness problem too. If rows are inserted while a user pages, the window shifts underneath them: items get skipped or shown twice.

Keyset (cursor) pagination

Remember where you stopped and ask for what comes after it:

SELECT * FROM orders
WHERE (created_at, id) < (:last_created_at, :last_id)
ORDER BY created_at DESC, id DESC
LIMIT 20;

With an index on (created_at DESC, id DESC), the database seeks straight to the position and reads 20 rows. Page 500 costs the same as page 1.

Two requirements people forget:

• The sort key must be unique. created_at alone is not — two rows sharing a timestamp will be skipped or repeated at the page boundary. The tuple (created_at, id) is unique, and the row comparison above compares it as a tuple, not column by column.
• The cursor is opaque. Base64-encode it and return it as next_cursor. Once clients start parsing it, you can never change the sort key.

{
  "data": [],
  "next_cursor": "eyJjcmVhdGVkX2F0IjoiMjAyNi0wMS0wMlQxMDowMDowMFoiLCJpZCI6ODEyfQ=="
}

The trade-off is real: you lose "jump to page 47" and you lose a cheap total count. If the product genuinely needs numbered pages over a small, bounded list, offset is fine. Say the trade-off rather than declaring cursors universally correct.

Practice

Versioning and backward compatibility

What actually breaks a client

Safe (additive): adding an endpoint, adding an optional request field, adding a response field, adding a new value to an enum that clients only display.

Breaking: removing or renaming a field, changing a type ("42" → 42), making an optional request field required, tightening validation, changing a default, changing pagination semantics, adding an enum value clients must branch on.

That last pair is the subtle one. Adding status: "partially_refunded" is additive to a client that prints the status and breaking for a client with a switch statement over three known values. Whether an enum is extensible is part of your contract, and you should state it in the docs from day one.

Strategies, in the order most teams should try them

1. Don't version. Only make additive changes. This covers more ground than people expect, and it is free.
2. Version the representation, not the API — Accept: application/vnd.acme.v2+json. Purist, and awkward to test from a browser or a curl one-liner.
3. Version in the path — /v2/orders. Ugly, obvious, easy to route, easy to debug. Most large public APIs land here for exactly those reasons.

A useful framing: URL versioning is a routing decision and media-type versioning is a content negotiation decision. Both work. Pick one and never mix.

Deprecation

A version is not retired when you announce it. It is retired when traffic reaches zero. That means you need per-version, per-client usage metrics before you can set a date. State the sunset in a header so it shows up in client logs:

Deprecation: Sun, 01 Nov 2026 00:00:00 GMT
Sunset: Sun, 01 Feb 2027 00:00:00 GMT
Link: <https://api.acme.com/docs/v2-migration>; rel="deprecation"

Practice

Error contracts

Errors are part of your API surface. Clients branch on them, so they are as much a compatibility commitment as your success payloads.

{
  "type": "https://api.acme.com/errors/insufficient-funds",
  "title": "Insufficient funds",
  "status": 422,
  "detail": "Account 812 has 1200 cents available, 4000 requested.",
  "instance": "/payments/9f2c",
  "code": "insufficient_funds",
  "errors": [
    { "field": "amount_cents", "code": "exceeds_balance" }
  ]
}

That is RFC 9457 (Problem Details) plus a stable machine-readable code. The important properties:

• A stable code, separate from the human message. Clients branch on the code. The message is for humans and may be rewritten or translated at any time.
• Field-level detail for validation errors, so a form can highlight the right input.
• No leaked internals. Never return a raw SQL error, a stack trace, or a constraint name from the driver. duplicate key value violates unique constraint "one_active_price" is a database implementation detail; translate it at the boundary.

Authentication and authorization

Enough to speak confidently, without pretending to be an identity specialist.

Authentication is who you are. Authorization is what you may do. Different failures: 401 and 403.

Token choices. Opaque tokens are random strings looked up server-side — revocation is instant, but every request costs a lookup. JWTs are self-describing and verified by signature, so no lookup is needed, but they cannot be revoked before expiry without reintroducing a lookup (a denylist), which gives back the property you chose JWTs to avoid. The usual compromise: short-lived access tokens (5–15 minutes) plus a long-lived refresh token that is checked server-side.

Where tokens live in a browser. localStorage is readable by any XSS on the page. An HttpOnly; Secure; SameSite cookie is not, but it is submitted automatically, which is what makes CSRF possible — so you need a CSRF token or strict SameSite. There is no option without a trade-off; know which one you took.

Scopes and permissions. A scope says what a token may do. It does not say what the user may do to a specific row. orders:read does not mean "read order 812" — you still have to check tenancy on every query. Saying this unprompted signals you have shipped multi-tenant software.

Rate limiting

Return 429 with the numbers the client needs to behave:

HTTP/1.1 429 Too Many Requests
Retry-After: 30
RateLimit-Limit: 1000
RateLimit-Remaining: 0
RateLimit-Reset: 30

Token bucket is the usual algorithm: a bucket refills at a steady rate and each request takes a token. It permits short bursts (up to bucket size) while bounding the sustained rate — which matches how real clients behave better than a fixed window does.

Fixed windows have a well-known edge: a client can send the full quota at 11:59:59 and the full quota again at 12:00:00, doubling the intended rate across the boundary. Sliding windows fix it at the cost of more state.

Limit per API key or per tenant, not per IP. Mobile carriers and corporate networks put thousands of users behind one address.

Caching and optimistic concurrency

One header does two jobs that look unrelated: not sending a body the client already has, and not overwriting an edit the client never saw.

GET /orders/812
→ 200 OK
  ETag: "order-812-v7"
  Cache-Control: private, no-cache

Caching — the client sends If-None-Match: "order-812-v7" and you answer 304 Not Modified with no body when it still matches.

Lost update prevention — the client sends If-Match: "order-812-v7" on a write. If the resource changed since, you answer 412 Precondition Failed instead of silently overwriting someone else's edit. This is optimistic concurrency control, and it is the HTTP expression of the same idea as a version column.

Without it, two people editing the same record produce last-write-wins, and the first person's change vanishes with no error anywhere.

Who is allowed to keep a copy

Cache-Control is not one setting. It is a set of instructions addressed to different audiences, and the audiences have different privacy properties — the browser cache holds one user's data, a CDN holds one copy for everyone.

no-cache and no-store sound like synonyms and do opposite things. no-cache still stores the response and only forbids using it without asking. no-store forbids writing it down at all. If you mean "never persist this", no-store is the one.

export async function GET(req: Request) {
  const user = await authenticate(req);
  const inbox = await getInbox(user.id);
 
  return Response.json(inbox, {
    headers: { "Cache-Control": "public, max-age=60" },
  });
}

return Response.json(inbox, {
  headers: {
    "Cache-Control": "private, no-store",
    Vary: "Authorization",
  },
});

Conditional GET, and what it actually saves

export async function GET(req: Request, { params }: { params: { id: string } }) {
  const order = await db.order.findUnique({
    where: { id: params.id },
    select: { id: true, version: true, status: true, totalCents: true },
  });
  if (!order) return new Response(null, { status: 404 });
 
  const etag = `"order-${order.id}-v${order.version}"`;
  const headers = { ETag: etag, "Cache-Control": "private, no-cache" };
 
  if (req.headers.get("if-none-match") === etag) {
    return new Response(null, { status: 304, headers });
  }
 
  return Response.json(order, { headers });
}

A 304 always saves bandwidth. It saves work only when the validator is cheaper than the response it replaces. Hashing the serialized body means running every query, building the whole payload, and then throwing it away — the client's bill goes down, yours does not. Deriving the tag from a version column means one narrow read decides the outcome.

SELECT count(*) AS n, coalesce(max(updated_at), 'epoch') AS m
FROM orders WHERE customer_id = $1;
-- ETag: "orders-c412-n42-m1719"

If-Match: the same header on the write path

The check and the write have to be one statement. A SELECT to compare the version followed by an UPDATE is the same read-then-write race that idempotency keys have to avoid, just with a different prize:

const expected = req.headers.get("if-match");
if (!expected) return new Response(null, { status: 428 });
 
const version = Number(expected.match(/v(\d+)"$/)?.[1]);
 
const { count } = await db.order.updateMany({
  where: { id, version },
  data: { status: body.status, version: { increment: 1 } },
});
 
if (count === 0) {
  const current = await db.order.findUnique({ where: { id }, select: { version: true } });
  return Response.json(
    { type: "/errors/stale-version", title: "The order changed since you loaded it" },
    { status: current ? 412 : 404, headers: current ? { ETag: `"order-${id}-v${current.version}"` } : {} },
  );
}

updateMany is not a bulk call here — it is how you get a predicate beyond the primary key plus a row count back. The count is the answer: one means you held the current version, zero means someone moved it.

const res = await save(draft, etag);
 
if (res.status === 412) {
  const fresh = await refetch();            // has the new ETag
  const conflicts = diff(base, draft, fresh);
  if (conflicts.length === 0) return save(merge(draft, fresh), fresh.etag);
  return showConflictUI(conflicts);         // a human decides
}

When the key expires, everyone arrives at once

A hot entry expiring is not a cache miss. It is N concurrent cache misses, and they all reach the origin before the first one finishes writing the new value back.

At the edge, two numbers instead of one:

Cache-Control: public, s-maxage=60, stale-while-revalidate=300

Fresh for 60 seconds. For the next 300, a stale copy is served immediately while a single background request refreshes it. Nobody waits on the origin, and the origin sees one request per refresh rather than one per reader.

In-process, the same idea is a map of in-flight promises:

const inFlight = new Map<string, Promise<unknown>>();
 
function singleFlight<T>(key: string, load: () => Promise<T>): Promise<T> {
  const existing = inFlight.get(key) as Promise<T> | undefined;
  if (existing) return existing;
 
  const promise = load().finally(() => inFlight.delete(key));
  inFlight.set(key, promise);
  return promise;
}

const lock = await redis.set(`lock:${key}`, id, { NX: true, PX: 5000 });
if (!lock) return serveStale(key) ?? waitForRefresh(key);

const ttl = base * (0.9 + Math.random() * 0.2);   // ±10% jitter

Long-running work

Do not hold a connection open for two minutes. Accept the work and hand back somewhere to look:

POST /exports
→ 202 Accepted
  Location: /exports/9f2c
 
GET /exports/9f2c
→ 200 OK
  {"status": "running", "progress": 0.42}
 
GET /exports/9f2c
→ 200 OK
  {"status": "succeeded", "result_url": "https://..."}

The status resource is a real resource with its own lifecycle. This also gives retries somewhere safe to land: combined with an idempotency key, a retried POST /exports returns the same Location instead of starting a second export.

Webhooks

You are now a client of someone else's flaky endpoint. Four things to get right:

Sign the payload. HMAC-SHA256 over the raw body plus a timestamp, sent as a header. The timestamp prevents replay; the receiver rejects anything older than a few minutes. The receiver must verify against the raw bytes, because re-serialising the JSON changes them.

Retry with exponential backoff and a cap. Something like 1m, 5m, 25m, 2h, then a dead letter queue. Add jitter so a recovering consumer is not hit by every pending delivery simultaneously.

Deliver at least once, never exactly once. You cannot distinguish "the consumer did not receive it" from "the consumer received it and the acknowledgement was lost." So you retry, and duplicates happen. Include a stable event_id and tell consumers to deduplicate on it.

Order is not guaranteed. Retries reorder events by definition. Either include enough state in each event that order does not matter, or include a sequence number and let consumers discard stale ones.

Bulk endpoints and partial failure

The moment you accept an array, you have to answer: what if item 7 fails?

All-or-nothing — wrap it in a transaction, fail the whole request, return 400. Simple to reason about, painful for a client submitting 500 items where one is bad.

Per-item results — return 207 Multi-Status (or 200 with a result array) where each entry carries its own status:

{
  "results": [
    { "index": 0, "status": 201, "id": "ord_1" },
    { "index": 1, "status": 422, "code": "invalid_currency" }
  ]
}

Either is defensible. What is not defensible is returning 200 and quietly dropping the failures. Pick one, document it, and make retrying the failed subset possible — which means per-item idempotency keys, not one key for the batch.

REST, GraphQL, gRPC

A short, honest comparison rather than advocacy.

REST/HTTP+JSON. Universal tooling, cacheable by URL, debuggable with curl. Tends toward over-fetching (you get the whole resource) and under-fetching (a screen needs four requests).

GraphQL. The client asks for exactly the fields it needs, which genuinely helps client-heavy products with many screen shapes. The costs are real: HTTP caching mostly stops working because everything is a POST to one URL; the N+1 problem moves into your resolvers and needs batching (DataLoader) to stay survivable; and query cost analysis becomes a security requirement, because a nested query is a denial-of-service vector.

gRPC. Binary protobuf over HTTP/2, generated clients, streaming, and a schema that is enforced rather than documented. Excellent between your own services. Awkward from a browser without a proxy, and harder to debug by hand.

The framing that lands: REST for public and partner APIs, gRPC between internal services, GraphQL when one API serves many differently-shaped clients and you are prepared to own the caching and cost-analysis work it moves onto you.

Contract first

Write the OpenAPI (or protobuf) definition before the handler. Generate the client from it. Validate requests and responses against it in tests. Diff it in CI and fail the build on a breaking change.

This turns "don't break the contract" from a code-review convention into something the pipeline enforces, and it is a strong thing to describe in an interview because it is a process answer, not a trivia answer.

Recall checklist

Cover the right column and see if you can produce it.

• Which methods are safe, which are idempotent, and why it matters for retries
• Why PATCH usually is not idempotent
• The three steps of idempotency-key handling, and why the unique constraint does the work
• What happens when the same key arrives with a different body
• Why the key is scoped to an attempt rather than to a click or a session
• What a page reload does to a client-generated key, and how a server-issued identifier closes that gap
• Why OFFSET 10000 is slow, in terms of what the database physically does
• Why a keyset cursor needs a unique sort key
• Three changes that are additive and three that are breaking
• Why you cannot pick a sunset date without per-client usage metrics
• Why 200 with {"success": false} is a broken error contract
• The revocation trade-off between JWTs and opaque tokens
• Token bucket versus fixed window, and the boundary burst problem
• If-None-Match versus If-Match — caching versus lost-update prevention
• Which directive binds the browser, which binds the CDN, and what private protects
• Why no-cache and no-store are not synonyms
• When a 304 saves work and when it only saves bandwidth
• Why the version check and the write have to be the same statement
• What a client should do with a 412, and why auto-retrying is last-write-wins
• Why a hot key expiring is a load spike, and what jitter and single flight each fix
• Why webhook delivery is at-least-once and what that obliges the consumer to do
• Two defensible answers for bulk partial failure
• One real cost of GraphQL and one real cost of gRPC