API Design & Communication

Building Blocks

• Request/Response Model: HTTP is strictly client-initiated: the client sends a request, the server sends one response, and the exchange ends. There is no server push in classic HTTP (that requires WebSockets, SSE, or HTTP/2 push, which was largely abandoned). This simple model is what lets intermediaries cache, retry, and route traffic without application knowledge.
• Methods and Semantics: HTTP methods declare intent. GET reads and is safe + idempotent + cacheable. POST creates or triggers processing and is neither. PUT replaces a resource at a known URL and is idempotent. PATCH applies a partial update (not guaranteed idempotent). DELETE removes a resource and is idempotent. These semantics tell intermediaries when it is safe to retry or cache: a network can safely replay a GET or PUT, but replaying a POST can double-charge a card.
• Status Code Families: Status codes compress outcomes into machine-readable families: 2xx success (200 OK, 201 Created, 204 No Content), 3xx redirects (301 Moved Permanently, 304 Not Modified — the backbone of HTTP caching), 4xx client errors (400 Bad Request, 401 Unauthenticated, 403 Forbidden, 404 Not Found, 429 Too Many Requests), and 5xx server errors (500, 502 Bad Gateway, 503 Service Unavailable, 504 Gateway Timeout). Load balancers, monitoring, and retry logic all key off these families.
• Headers: Headers carry metadata that steers behavior: Content-Type and Accept negotiate formats, Cache-Control and ETag drive caching, Authorization carries credentials, Location points to created resources, Retry-After tells clients when to come back. Well-designed APIs use headers instead of inventing custom body fields, because infrastructure already understands them.
• Statelessness: Each request must contain everything the server needs — no server-side memory of previous requests is assumed. This is the property that lets any request hit any replica behind a load balancer, which is the foundation of horizontal scaling. State lives in databases, caches, and client-held tokens (JWTs), not in the web server.
• TLS (HTTPS): HTTPS is HTTP over a TLS-encrypted channel, providing confidentiality, integrity, and server authentication via certificates. Modern systems terminate TLS at a load balancer or CDN edge, then re-encrypt or use mTLS inside the data center. TLS adds a handshake round trip (reduced by TLS 1.3's 1-RTT and 0-RTT resumption) but is non-negotiable for anything carrying user data.

Definitions

Idempotency

An operation is idempotent if performing it multiple times has the same effect as performing it once.

• GET, PUT, and DELETE are idempotent by spec; POST and PATCH are not guaranteed to be.
• Idempotency is what makes automatic retries safe — a timeout on a PUT can be replayed blindly.
• For non-idempotent operations like payments, add idempotency keys (e.g., Stripe's Idempotency-Key header) so the server can deduplicate retries.

Safe Method

A method that does not modify server state — in practice, GET and HEAD.

• Safe methods can be prefetched by browsers and cached by CDNs without fear.
• A GET that mutates state (e.g., /deleteUser?id=5) is a classic bug: web crawlers and prefetchers will trigger it.
• Safety is a promise to intermediaries; breaking it breaks caches and retry logic invisibly.

Multiplexing

Sending multiple concurrent request/response streams over a single connection, as in HTTP/2.

• HTTP/1.1 pipelines poorly, so browsers open ~6 parallel connections per host as a workaround.
• HTTP/2 splits messages into frames tagged with stream IDs, so one connection can carry hundreds of interleaved streams.
• Multiplexing removes application-level head-of-line blocking, though TCP-level head-of-line blocking remains (fixed by HTTP/3).

Head-of-Line Blocking

When one delayed message stalls all messages behind it in the same channel.

• In HTTP/1.1, a slow response blocks the next request on that connection.
• In HTTP/2 over TCP, a single lost TCP packet stalls all streams on the connection until retransmission arrives.
• HTTP/3 (over QUIC/UDP) gives each stream independent delivery, so one lost packet only stalls its own stream.

Connection Reuse (Keep-Alive)

Keeping a TCP/TLS connection open across multiple requests instead of paying a new handshake each time.

• A fresh HTTPS connection costs a TCP handshake (1 RTT) plus TLS handshake (1-2 RTTs) — significant on high-latency links.
• HTTP/1.1 keep-alive and HTTP/2's single multiplexed connection exist specifically to amortize this cost.
• At the server side, millions of idle keep-alive connections consume memory and file descriptors, which is why connection limits and timeouts matter at scale.

HTTP Caching

Storing responses so future requests can be served without hitting the origin server.

• Cache-Control directives (max-age, no-store, private/public) declare cacheability; ETag and If-None-Match enable cheap revalidation.
• A 304 Not Modified response sends no body, saving bandwidth when the client's copy is still fresh.
• Only safe, idempotent methods with cacheable status codes should be cached — caching a personalized response with the wrong headers leaks data between users.

Patterns

• Idempotency Keys for Mutations — Any POST that charges money, creates orders, or performs a non-reversible action where client retries are possible.
• Cache-Friendly Read APIs — Read-heavy endpoints serving shared, slowly-changing data (catalogs, feeds, public profiles).
• Correct Status Codes as Control Signals — Always — status codes are how load balancers, clients, and observability tools understand your system.
• TLS Termination at the Edge — Any public-facing service where you want centralized certificate management and cheap L7 routing.

Strategies

• Choose the Right HTTP Version Per Hop When: When designing client-to-edge and edge-to-origin paths with different latency and control needs. How: Use HTTP/3 (or HTTP/2) from mobile clients to the CDN edge to survive packet loss and connection setup costs; use HTTP/2 or even HTTP/1.1 inside the data center where networks are reliable and tooling is mature. Gateways translate between versions. Example: Cloudflare and Google front-ends speak HTTP/3 to browsers but often proxy to origins over HTTP/1.1 or HTTP/2, getting QUIC's mobile benefits without rewriting backends.
• Design Mutations Around Idempotency When: Whenever a client can retry a state-changing request after a timeout. How: Prefer PUT/PATCH with client-supplied resource IDs so retries naturally converge. For POST, require an idempotency key, store the first response against that key, and replay it on duplicates. Example: An order creation API accepts a client-generated order UUID; a retried POST returns the existing order instead of creating a duplicate.
• Exploit HTTP Caching Deliberately When: Read-heavy systems where origin load and latency dominate cost. How: Partition responses into public/shared vs private/user-specific, assign explicit Cache-Control and ETag headers, and design URLs so that changing content changes the URL (cache-busting via content hashes). Example: Static JS bundles ship with a content-hash filename and max-age=1year, while HTML is no-cache with an ETag — deploys roll out instantly without stale assets.
• Amortize Connection Costs When: High-fan-out services making thousands of downstream calls per second. How: Maintain connection pools with keep-alive to downstream services, bound pool size to protect the downstream, and set idle timeouts shorter than the server's to avoid racing closed connections. Example: A checkout service pools 200 keep-alive connections to the inventory service, cutting per-call latency by ~40ms of TCP+TLS setup on every request.
• Use Status Codes to Drive Retry Policy When: Any client or service mesh implementing automatic retries. How: Retry 5xx and 429 (with backoff, honoring Retry-After); never retry 4xx except 408/429, since the request itself is invalid; treat timeouts as unknown outcomes and apply idempotency safeguards. Example: A payment client retries a 503 twice with exponential backoff but surfaces a 402 immediately — retrying cannot fix insufficient funds.

Tradeoffs

Real World

Quiz

A client POSTs a payment request and the connection times out. Why is blindly retrying dangerous, and what fixes it?

1. POST is not idempotent, so a retry may charge twice; an idempotency key lets the server deduplicate
2. POST is encrypted, so retries corrupt TLS; switching to HTTP/2 fixes it
3. Timeouts always mean the server failed; retrying is always safe
4. POST responses are cached, so the retry returns stale data; add Cache-Control

A timeout means the outcome is unknown — the server may have processed it. Since POST is not idempotent, retries need an explicit idempotency key so the server can return the original result.

Which status code family should an automatic retry policy generally NOT retry (other than 408/429)?

1. 5xx server errors
2. 3xx redirects
3. 4xx client errors
4. 2xx successes

4xx means the request itself is invalid (bad payload, missing auth, wrong resource) — retrying the same request will fail identically. 5xx and 429 are transient and retryable with backoff.

What key problem does HTTP/2 introduce that HTTP/3 solves?

1. HTTP/2 cannot encrypt traffic, HTTP/3 adds TLS
2. HTTP/2 multiplexes streams over one TCP connection, so one lost packet stalls all streams; HTTP/3 over QUIC gives streams independent delivery
3. HTTP/2 is text-based and slow to parse, HTTP/3 is binary
4. HTTP/2 does not support headers, HTTP/3 adds them

HTTP/2 fixed application-level head-of-line blocking via multiplexing, but all streams share one ordered TCP byte stream — a single lost packet blocks everything. QUIC moves streams into the transport so loss only affects one stream.

Why is HTTP's statelessness crucial for horizontal scaling?

1. It makes requests smaller, so servers process them faster
2. It allows any request to be handled by any replica behind a load balancer, since no server memory of prior requests is required
3. It removes the need for TLS certificates on every server
4. It guarantees responses are cacheable by CDNs

State lives in databases, caches, and client tokens rather than the web server, so load balancers can route each request to any healthy replica — the core of horizontal scale-out.

Your API serves a public product catalog read 50,000 times/second but updated hourly. Which HTTP feature gives the biggest win?

1. Switching all endpoints from GET to POST for better throughput
2. Enabling HTTP/1.1 pipelining on the origin server
3. Increasing the TLS session timeout
4. Cache-Control with max-age plus ETag, letting CDNs serve most traffic at the edge

Read-heavy, slowly-changing, shared data is the ideal caching case: edge caches absorb the vast majority of requests, and ETag revalidation makes freshness checks cheap when the TTL expires.