API Design Workbook

APIs as contracts between systems. The product-architecture lens, why API design is its own discipline, and what good looks like.

APIs as products. Monetisation, partner programs, developer experience as a moat, why Stripe is Stripe.

Why IP is the everything-over-IP-and-IP-over-everything pivot, and what that means for API designers building on top.

The two performance dimensions every API designer must hold in head. The 100 ms human-perception ceiling and the throughput-vs-latency trade.

Sockets as the OS-level primitive every HTTP server stands on. Why API designers should know what's underneath.

URLs, HTTP, HTML — the three-letter trio Tim Berners-Lee picked in 1989 and the rest of API design has been catching up with since.

On the wire, every API is bytes. The trade-off between human-readable and compact, and why both have their place.

Methods, status codes, headers, persistent connections — the parts of HTTP every API designer must own.

Pipelining → multiplexing → QUIC. How each version solved the previous one's head-of-line problem and what that buys API designers.

Calling a remote function as if it were local. The 'function-call' abstraction, its leaks, and where it's still the right call.

Upgrade-handshake, full-duplex frames, the long-lived connection model. When push beats poll.

The trio every API designer must read fluently. Why JSON won, where XML still lives, what YAML costs in subtle bugs.

When the wire matters more than the diff. Schema-first vs schema-less, evolution semantics, the size-vs-debuggability trade-off.

REST, GraphQL, gRPC, SOAP, WebSocket, webhook. The catalogue, when each is right, and why every team thinks theirs is special.

Resources, verbs, statelessness, cache, uniform interface, HATEOAS. Fielding's PhD thesis applied to your CRUD endpoints.

Path conventions, status codes that fit, payload shape, pagination, filtering, the bulk-operations friction every REST API hits.

One endpoint, client-shaped responses, the N+1 problem, schema as the contract. When the flexibility earns its complexity.

Service-definition-first, code-generated clients, streaming variants, the polyglot internal-RPC story that won at Google.

The honest trade-offs. Latency, payload size, tooling, debuggability, mobile-friendliness, where each one breaks first.

The threat model: authentication, authorization, integrity, confidentiality, availability. What an API designer owns.

TLS 1.2 vs 1.3 handshake, cert chains, mTLS, the cost of a TLS terminator, why HTTPS is non-negotiable.

Validate at the boundary, reject early, normalise once. SQL/NoSQL injection, type confusion, the OWASP API top-10.

The same-origin policy, preflight, Access-Control-Allow-*, credentials, the wildcard that breaks production.

Who you are vs what you can do. The two-word vocabulary every API designer must use precisely.

Authorization Code + PKCE, refresh tokens, scopes, the four roles. The protocol every modern API uses and gets wrong half the time.

OIDC layers identity on OAuth; SAML is the older enterprise SSO. When to pick each, and why both still ship in 2026.

The checklist: TLS, validate, AuthN, AuthZ, rate limit, audit. The mnemonic an API designer carries into every review.

URI versioning, header versioning, semantic versioning. The choice that ages well vs the one that bites every quarter.

Backward-compatible additions, breaking-change taxonomy, deprecation timelines. How successful APIs survive a decade.

Token bucket, leaky bucket, fixed window, sliding window. Per-user vs per-IP, the 429 contract, and the burst question.

When the server shapes its response to the client (mobile vs web vs partner). The BFF pattern in API form.

Eager vs lazy, batch vs single, paginated vs streamed. The four levers every API designer pulls.

Webhooks, server-sent events, Kafka, message queues. The push-shaped alternative to request/response.

Stateful sessions over stateless HTTP, the SameSite / Secure / HttpOnly trio, when JWTs replace cookies and when they shouldn't.

Idempotency keys, safe retries, the difference between idempotent and safe verbs. Why payments APIs care most.

The render seam shapes the API contract. SSR's full-payload vs CSR's many-small-calls, and the hybrid in between.

Critical render path, third-party blockers, what an API designer can give the front-end to win the LCP and CLS scores.

preload, prefetch, dns-prefetch, preconnect. Debouncing user input to API calls; the trade-off between fresh and floody.

Closed → Open → Half-Open. Failing fast when a dependency is sick; the cascade-prevention pattern Netflix made famous.

Exponential backoff, jitter, retry budgets, the retry-storm that takes down a recovering service. Idempotency is mandatory.

Browser, CDN, gateway, app, database. Where to cache, what to cache, the cache-invalidation problem the joke is about.

Logs, metrics, traces, the four golden signals (latency, traffic, errors, saturation), what the on-call must see in 5 seconds.

Processing time + network time + queueing. The numbers every engineer should know (memory, SSD, datacenter RTT, cross-continent RTT).

A repeatable seven-step recipe for an API-design interview: requirements, endpoints, data, constraints, auth, evolution, latency.

Query, suggest, rank, paginate. Where latency budget lives and how to write a search API that won't go viral on the wrong page.

Upload, download, range requests, multipart, signed URLs, resumability. The S3-shaped contract every backend reinvents.

Threaded comments, pagination by cursor, moderation hooks, the reaction subsystem. The CRUD that scales to millions of nodes.

Topics, subscribers, fan-out, at-least-once vs exactly-once. The asynchronous backbone of every modern microservice mesh.

Upload pipeline, transcode, ABR manifests, CDN, recommendation. The biggest video service in the world, from the API's side.

Real-time delivery, presence, read receipts, group threads, end-to-end encryption. WebSockets + a careful state machine.

Tiles, geocoding, routing, places, distance matrix. The geospatial endpoints behind a billion daily queries.

Game lifecycle, move validation, time control, spectator stream. The cleanest turn-based-game API in the catalogue.

Meetings, participants, signalling, recording, webhooks. The video-conferencing API behind a pandemic-era infrastructure.

Problem, submission, judge, leaderboard. The fan-out from problem-fetch to async judge to result subscription.

PaymentIntent, charge, refund, webhook, the cards-network interaction. The gold-standard for payments-API design.

Tweet, timeline, follow graph, search, streaming. The read-heavy fan-out problem at planet scale.

Riders, drivers, dispatch, trip lifecycle, surge. Real-time matching with geospatial constraints.

Price-tracking for Amazon products. A scraper-shaped API that must respect a partner's rate limits and ToS.

Matchmaking, lobby, real-time game state, leaderboards, anti-cheat hooks. Latency-sensitive APIs where 50 ms is everything.

Deploy bugs, capacity, contract drift, dependency outage, cascading retries. The five patterns that recur in every public postmortem.

An un-removed feature flag (SMARS) revived dead code on one of eight servers. A trading-API contract that didn't enforce safety.

A typo in a maintenance command cascaded through the S3 control plane. The API's read path went down and took half the Internet.

Two short case studies of cascading API failures from major social and mobility APIs. What the contract didn't say.