APIs & Protocols | System Design Interview Handbook

🔗

REST: The Default

resources, verbs, and statelessness

REST models everything as resources addressed by URL and manipulated with HTTP verbs. GET /users/42 reads, POST /users creates, PUT/PATCH updates, DELETE removes. Status codes carry the outcome: 2xx success, 4xx the client's fault, 5xx the server's.

It's the default for a reason. It rides plain HTTP, so every browser, proxy, and CDN understands it; GETs are cacheable for free; and it's stateless — each request carries everything it needs, so any server can handle any request and you scale by adding boxes (Scaling Patterns).

Code	Means	Typical use
200 / 201	OK / Created	Read succeeded / resource created
400	Bad request	Malformed input, failed validation
401 / 403	Unauthenticated / forbidden	No valid identity / not allowed
404	Not found	Resource doesn't exist
409	Conflict	Version clash, duplicate create
429	Too many requests	Rate limited (Rate Limiter)
5xx	Server error	Retryable if the operation is idempotent

⚠️

REST creaks when the resource shape doesn't match what the client needs. Mobile screens that need data from five resources make five round trips (chatty), or a fat endpoint returns fields nobody reads (over-fetching). Those two pains are exactly what GraphQL and gRPC-streaming set out to fix.

⚡

gRPC: Fast, Typed, Internal

the service-to-service workhorse

gRPC defines the contract in a Protobuf schema, generates client and server stubs in every language, and sends compact binary frames over HTTP/2. Smaller payloads than JSON, a real typed contract checked at compile time, and multiplexed connections. It also supports streaming — client, server, or bidirectional — which REST can't do cleanly.

That combination wins inside a system: high-volume, low-latency calls between services that you control on both ends (Microservices).

Where it shines east-west traffic

Internal service mesh, tight latency budgets, strict contracts across many languages, and streaming RPCs. The binary encoding and HTTP/2 multiplexing pay off most where call volume is highest.

Where it doesn't the browser wall

Browsers can't speak raw gRPC — you need a gRPC-Web proxy. Payloads aren't human-readable, so debugging needs tooling, and plain HTTP caches can't see inside. For public, browser-facing APIs, REST is still the safer default.

◈

GraphQL: Client-Shaped Queries

one endpoint, you ask for exactly what you need

GraphQL exposes a single endpoint and a typed schema. The client sends a query describing precisely the fields it wants, across whatever entities, and gets back that exact shape in one round trip. No over-fetching, no under-fetching, no five calls to stitch a screen together.

The cost lands on the server and the edges. Caching is hard — every query is a unique POST body, so HTTP caching by URL no longer works. And the flexible query surface makes the N+1 problem easy to trigger: one query for a list, then one more per item, unless you batch with a loader.

  REST                              GraphQL
  GET /users/42        ─┐           POST /graphql
  GET /users/42/posts  ─┼─ 3 trips  { user(id:42) {          ─┐
  GET /users/42/photos ─┘             name                   │  1 trip,
                                      posts { title }         │  exact shape
   over/under-fetch,                  photos { url } } }     ─┘
   fixed shapes                     server resolves each field

💡

GraphQL earns its complexity when you have many client types pulling different shapes from the same data — a web app, an iOS app, and partners all hitting one graph — or as an aggregation layer over several backend services. For a single client with stable needs, it's usually more machinery than the problem deserves (Tradeoffs).

🔀

Request-Response vs Event-Driven

coupling now, or decoupling later

All three styles above are synchronous: the caller sends a request and blocks for the answer. Simple, immediate, and the right default — but it couples caller to callee. If the callee is slow or down, the caller waits or fails with it.

The alternative is event-driven: the producer emits an event and moves on; consumers react whenever they can. That decouples failure domains and absorbs spikes, at the price of eventual consistency and harder debugging — you trade a clear call stack for a chain of messages (Messaging).

	Request-response	Event-driven
Coupling	Caller waits on callee	Producer and consumer independent
Result	Immediate, in-band	Later, out-of-band
Failure	Propagates to caller	Contained; retried from the queue
Spikes	Hit the callee directly	Absorbed by the queue
Best for	Reads, anything needing an answer now	Fire-and-forget work, fan-out, decoupling

ℹ️

The common pattern is both: respond synchronously with an acknowledgment, then do the heavy work asynchronously. "Upload accepted" returns in 50ms; transcoding runs off a queue. The user isn't blocked on work they don't need to wait for (Video Streaming).

🧷

Details That Come Up

pagination, versioning, idempotency

A handful of API details show up in almost every design round. Knowing the right answer to each is cheap credibility.

Pagination: cursor beats offset at scale

Offset (LIMIT 20 OFFSET 10000) is easy but the DB scans and discards every skipped row, so deep pages get slow, and inserts shift the window and cause skips or dupes.

Cursor passes an opaque pointer to the last item seen (WHERE id > last). Constant-time regardless of depth and stable under inserts. The default for feeds and large lists.

Idempotency keys safe retries on writes

A retried POST /payments must not charge twice. The client sends a unique Idempotency-Key; the server records it on first use and, on a replay, returns the stored result instead of re-executing.

This is what makes mutations safe to retry over a flaky network (Concurrency Control).

Versioning and rate-limit headers the rest of the contract

Versioning keeps you from breaking existing clients when the shape changes: a URL prefix (/v2/) is the blunt, visible option; a header or media-type version is cleaner but easier to miss. Whichever you pick, additive changes shouldn't need a new version — only breaking ones.

Rate-limit headers (X-RateLimit-Remaining, Retry-After) tell a well-behaved client how much budget is left and when to come back, turning a 429 into a signal instead of a surprise (Rate Limiter).

📋

Quick Reference

the three styles on one card

	REST	gRPC	GraphQL
Transport	HTTP/1.1+	HTTP/2	HTTP (usually POST)
Payload	JSON (text)	Protobuf (binary)	JSON, client-shaped
Contract	Convention / OpenAPI	Strict, generated stubs	Typed schema
Streaming	No (awkward)	Yes, bidirectional	Via subscriptions
HTTP caching	Free on GET	No	Hard
Browser	Native	Needs proxy	Native
Best fit	Public, browser-facing APIs	Internal service-to-service	Many clients, aggregation layer

Pagination	How	Cost
Offset	`LIMIT/OFFSET`	Slow deep pages, drifts on insert
Cursor	Pointer to last item seen	Constant-time, stable — use at scale

ℹ️

The one-liners to keep ready. REST for public and browser-facing; gRPC for internal high-volume; GraphQL when many clients pull different shapes. Sync for answers you need now, async to decouple and absorb spikes. Cursor pagination at scale, idempotency keys on retryable writes, and a versioning story before you ship v1.