Fundamentals

API Design & Idempotency

Design external APIs that are paginated, versioned, and safe under retries.

Intermediate, about 55 minutes to read, 4 open questions to practise.

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.

100%
ClientGatewayServiceStore

Walkthrough

Idempotent POST

Retries must not double-charge

1 / 4

100%

Client POSTs /charges with Idempotency-Key: abc. Network may retry.

Read the walkthrough as text

Worked example, partner payments API + million-row activity feed.

  1. POST /charges: require Idempotency-Key; Redis/SQL stores outcome 48h; duplicate network retry returns identical charge id, interviewers expect you to say this unprompted.
  2. GET /charges: limit=50&cursor=eyJjcmVhdGVkX2F0Ijo... keyset pagination; document no cheap total count.
  3. Explain OFFSET trap: page 5000 at offset 100000 scans, slow + inconsistent.
  4. POST /refunds: 202 + poll; webhook refund.completed optional with signature.
  5. GET /orders/{id}?include=line_items,shipment, one trip vs 21 calls.
  6. Version `/v2` when renaming amount_cents → amount; v1 maintained 12 months.
  7. Timeouts: client 30s; server 25s; idempotent creates safe on client retry.
  1. Webhook contract: X-Signature HMAC; receiver stores event_id processed.
  2. Load test note: cursor pagination keeps stable p99 on page 200; offset would degrade.
  3. 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

API contract napkin

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:

  1. Resources & verbs, idempotent GET/PUT/DELETE; careful POST.
  2. Idempotency, key storage, TTL, replay body.
  3. Pagination, cursor + stable sort column.
  4. Long operations, 202, status, webhook.
  5. Errors & retries, which status codes retry.
  6. Versioning & compatibility.
  7. Chatty client mitigation, expand/batch.

Phrases: “clients will retry POST,” “keyset pagination,” “honest async with 202.”

  1. Closing punch, “The contract outlives the implementation language.”
  1. Partner sandboxes, separate base URL and rate limits; idempotency keys scoped per environment.

Answer checklist

1. Resources and operations; sync vs async response. 2. Idempotency for unsafe retries (keys, upserts). 3. Pagination (cursor vs offset) for large lists. 4. Errors, timeouts, and versioning strategy. 5. Authn/z boundary in one sentence.

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

100%

Stronger sketch

Good

100%
  • 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

Ready to practise?

Write an answer, get AI coaching, then revise. You are not building a real system.

Practise with an open question

All systems lessons