1Understand
The idea
API design at scale is contract design under unreliable networks (mobile, partners, retries): clients retry, clocks skew, and partners integrate for years. You make dangerous operations idempotent, paginate large collections without deep OFFSET, surface long work honestly with 202 and status URLs, and keep errors predictable (code, request_id, retry guidance).
Versioning and auth boundaries should be boring and explicit so backend teams can swap databases without breaking mobile apps stuck on v1. The interview trap is beautiful REST nouns with unsafe POST retries that duplicate orders on every timeout.
Fat aggregates vs chatty N+1 reads is a product tradeoff, offer ?include= or batch endpoints when latency budgets demand one round trip.
A senior answer sounds like a published integration guide (retry matrix, cursor semantics, webhook signatures): what retries are safe, how pagination behaves under concurrent writes, how long idempotency keys live, and what the client should do on 429 vs 500, not a Swagger file dumped on the whiteboard.
Intuition
Idempotency. Idempotency-Key header on POST → store key → response snapshot (24-72h TTL). Replay returns same 201 body and same resource id. Alternative: client-generated id with PUT upsert semantics.
Pagination. Offset scans skipped rows, O(offset) pain and duplicates/skips under concurrent writes. Keyset/cursor on indexed (created_at, id) with stable sort; opaque cursor token encodes last seen tuple.
Async work. Transcode, bulk export, refund settlement → 202 Accepted, Location: /jobs/{id}, optional webhook. Do not hold HTTP 120s.
Errors. 4xx vs 5xx, only retry 429/503 with backoff; 400 validation is client bug. Include request_id for support correlation.
Versioning. /v1 prefix or Accept-Version; sunset timeline; never silent breaking JSON rename.
Rate limits & auth at gateway, related patterns but API should document 429 shape.
gRPC vs REST one-liner: typing/streaming vs browser ergonomics. Pick with audience.
Timeouts & contracts. Document client retry policy: safe methods vs unsafe POST. Server deadline slightly below client timeout so errors are JSON, not ambiguous hang. Webhooks sign payloads; include event id for idempotent receiver processing.
Partial responses. For large includes, cap depth and item count; return 413 or truncate with truncated=true metadata so mobile does not OOM.
What you will be able to do
- Make writes safe under client retry
- Paginate list endpoints without offset traps at scale
- Separate sync acknowledgment from async completion when needed
When this comes up
- Idempotency-Key
- Pagination
- REST vs RPC
- Retries and timeouts
2See it
Architecture sketch
Client talks to a contract
Versioned HTTP API with auth, pagination, and idempotent writes.
Walkthrough
Idempotent POST
Retries must not double-charge
1 / 4
Client POSTs /charges with Idempotency-Key: abc. Network may retry.
Read the walkthrough as text
Worked example, partner payments API + million-row activity feed.
- POST /charges: require
Idempotency-Key; Redis/SQL stores outcome 48h; duplicate network retry returns identical charge id, interviewers expect you to say this unprompted. - GET /charges:
limit=50&cursor=eyJjcmVhdGVkX2F0Ijo...keyset pagination; document no cheaptotalcount. - Explain OFFSET trap: page 5000 at offset 100000 scans, slow + inconsistent.
- POST /refunds: 202 + poll; webhook
refund.completedoptional with signature. - GET /orders/{id}?include=line_items,shipment, one trip vs 21 calls.
- Version `/v2` when renaming
amount_cents→amount; v1 maintained 12 months. - Timeouts: client 30s; server 25s; idempotent creates safe on client retry.
- Webhook contract:
X-SignatureHMAC; receiver storesevent_idprocessed. - Load test note: cursor pagination keeps stable p99 on page 200; offset would degrade.
- Partner onboarding: sandbox keys, separate idempotency namespace, lower rate limits.
What interviewers listen for: idempotency storage; cursor vs offset; 202 pattern; versioning; N+1 fix.
Napkin math
version in path: /v1/...
auth = Bearer JWT (or API key)
list = cursor pagination, page ≤ 100
POST money: Idempotency-Key header
errors = stable codes + retryable flag
Retries must not double-charge. Design for that.
3Answer it
How to answer in an interview
When “design REST API,” external integrators, mobile offline:
- Resources & verbs, idempotent GET/PUT/DELETE; careful POST.
- Idempotency, key storage, TTL, replay body.
- Pagination, cursor + stable sort column.
- Long operations, 202, status, webhook.
- Errors & retries, which status codes retry.
- Versioning & compatibility.
- Chatty client mitigation, expand/batch.
Phrases: “clients will retry POST,” “keyset pagination,” “honest async with 202.”
- Closing punch, “The contract outlives the implementation language.”
- Partner sandboxes, separate base URL and rate limits; idempotency keys scoped per environment.
Answer checklist
Tradeoffs & numbers
- Idempotency store: infra cost vs duplicate charge cost, always worth on payments.
- Opaque cursor: cannot jump to page 17, product accepts forward-only feeds.
- Fat JSON: fewer RTTs; larger payloads harder to cache.
- Sync 200 on async: lies to client, prefer 202.
- Public pagination totals: expensive
COUNT(*), separate endpoint or estimate. - When NOT cursor: tiny admin tables <1000 rows, offset acceptable.
- OpenAPI vs behavior: docs must match retry and cursor semantics, partners integrate from PDFs years later.
- Breaking changes: prefer additive JSON fields; never rename in place without version bump.
- Interview tip: say “unsafe POST retry” before the interviewer asks, shows production scar tissue.
- Documentation: partners integrate from PDFs, error codes table is part of the architecture.
- Mobile offline: queue unsafe POSTs client-side until connected; server idempotency still mandatory.
Kinds of questions (4)
Same pattern, different interview surfaces. Recognise which variant you are in before you answer.
Idempotent payments / creates
Example. Mobile client times out on POST /subscriptions; user taps submit again. Cover idempotent writes, cursor pagination (not deep OFFSET), timeout/retry matrix, and stable error shape with `request_id`.
How. Same Idempotency-Key header returns original subscription id and 201 body; no double billing period. Idempotency-Key on POST; cursor `next_page_token`; 202 + poll URL for long jobs; document safe retries.
Cursor pagination
Example. Social activity feed with 50M events; infinite scroll must not duplicate after new posts arrive. Cover idempotent writes, cursor pagination (not deep OFFSET), timeout/retry matrix, and stable error shape with `request_id`.
How. Keyset on `(created_at, id)` descending; opaque cursor; stable sort even when rows insert at top. Idempotency-Key on POST; cursor `next_page_token`; 202 + poll URL for long jobs; document safe retries.
Async 202 + status URL
Example. Government PDF export takes 12 minutes; HTTP client timeout is 60s. Cover idempotent writes, cursor pagination (not deep OFFSET), timeout/retry matrix, and stable error shape with `request_id`.
How. 202 with job id; GET /jobs/{id} progress; optional webhook; worker stores result in object store. Idempotency-Key on POST; cursor `next_page_token`; 202 + poll URL for long jobs; document safe retries.
API versioning
Example. Field `tax_id` renamed; enterprise partners still on v1 SDK embedded in appliances. Cover idempotent writes, cursor pagination (not deep OFFSET), timeout/retry matrix, and stable error shape with `request_id`.
How. /v1 maintains old shape 18 months; sunset headers; v2 additive migration guide, no silent JSON break. Idempotency-Key on POST; cursor `next_page_token`; 202 + poll URL for long jobs; document safe retries.
Common mistakes
Failure modes the AI coach watches for when you practise open questions.
Pagination under concurrent writes
Avoid. OFFSET 10000. Slow and unstable as rows insert/delete.
Prefer. Cursor / keyset on (created_at, id). Stable and index-friendly.
Weak sketch
Bad
Stronger sketch
Good
Unsafe retries
Why it happens. Gateways and mobile SDKs automatically retry timed-out POSTs, creating duplicate resources without idempotency contracts.
How it fails. POST /transfers creates a new wire transfer row on every duplicate request from client retry.
Fix. Idempotency-Key with stored response, or PUT with client-generated resource id and upsert semantics.
Offset pagination at scale
Why it happens. Large OFFSET forces the database to read and discard rows; concurrent inserts cause skipped or duplicate pages in feeds.
How it fails. Instagram-style feed `OFFSET 50000 LIMIT 20` on hot table for page 2500.
Fix. Keyset pagination with indexed sort columns; opaque cursor encoding last position.
Chatty API
Why it happens. Mobile RTT × 30 requests dominates perceived latency and burns rate limits even if each call is “fast.”
How it fails. Checkout UI loads cart, then 40 sequential GETs for product metadata one id at a time.
Fix. Batch endpoint or `?include=products`; server-side join for bounded fan-in.
4Practise
Concept check
A short quiz on this lesson before open questions. Optional, and it does not gate practice.
Open questions
- about 8 min
Idempotent create
Partners call `POST /transfers` to move money. Timeouts cause retries. Design idempotency: header or body field, what you store, TTL, and what response you return on duplicate submission with the same key.
- about 8 min
Cursor pages
An activity feed has 50M events. Clients page through history. Why is `OFFSET 200000 LIMIT 50` problematic? Design cursor-based pagination including stable sort columns and handling new items arriving while the user pages.
- about 8 min
202 and status
Report generation takes 3-10 minutes. Design the HTTP API: initial request, response codes, how the client polls or receives completion, and what you store while the job runs.
- about 8 min
Version breaking change
You must rename a response field and change its semantics. Half of clients are mobile apps you cannot force-update overnight. How do you version the API, route traffic, and sunset v1?
Ready to practise?
Write an answer, get AI coaching, then revise. You are not building a real system.