Compression: Cheaper Bytes, Not Fewer

JSON compresses embarrassingly well: repeated keys, quoted strings and whitespace give gzip a typical 5–10× ratio on API responses (brotli a little better at higher CPU). A 200KB response becomes ~30KB — on a 5 Mbps mobile link that is ~320ms of transfer collapsing to ~50ms, per request, for every consumer at once. For bandwidth-bound consumers this is the cheapest large win in the whole performance toolbox: no contract shape changes, no consumer code beyond standard HTTP support.

The price is CPU on both ends, paid per request. gzip at a mid level (6) compresses very roughly 50–100 MB/s per core; a service pushing 1,000 RPS of 100KB responses is asking one to two cores to do nothing but deflate. Decompression is ~5–10× cheaper, so the client's share is small — the provider carries the bill. That asymmetry is why the decision is per-endpoint and per-deployment: the same setting that is obviously right for a public mobile API is a pure loss on a CPU-bound internal service whose 3KB responses cross a datacenter switch.

Level tuning is a real dial, not a detail: gzip 1 gets most of the ratio for a third of the CPU of gzip 9, and for dynamic responses generated per-request, the last few percent of ratio are almost never worth the cores. Static or cacheable bodies invert this — compress once at maximum, serve many times (see Caching as a Contract Clause).

Compression on the web is negotiated, and the negotiation is a promise like any other. The client lists what it can decode in Accept-Encoding; the server picks one and declares it in Content-Encoding, or sends identity if there is no overlap. Two contract sins follow from skipping this. Sending compressed bytes without a correct Content-Encoding — or to a client that never offered it — hands the consumer garbage it will fail to parse with an error that looks like corruption. And compressing while ignoring Vary: Accept-Encoding poisons shared caches: a cache that stores the gzipped body and serves it to a client that only speaks identity has broken that client with a 200.

Document the behavior where consumers read: which encodings the API supports, whether large *request* bodies may be compressed (Content-Encoding on the request is rarer and needs explicit support and limits — a compressed request is also a decompression-bomb vector, so cap the expanded size), and the fact that Content-Length, when present, describes the compressed bytes on the wire. SDKs should negotiate by default so consumers get the win without reading any of this (see SDK Design: The Contract's User Interface).

Where compression runs matters operationally. Terminating it at the gateway or CDN centralizes the CPU and the configuration (one place to set levels, minimum sizes and content-type filters) and keeps application pods spending cores on application work (see The Gateway as Policy Boundary); compressing in the service keeps the bytes small across every internal hop, which matters when hops cross zones you pay for. Most stacks land on: edge compresses responses to the public internet, internal hops stay identity unless a cross-region link says otherwise.

Two edge cases earn attention. Streaming: compression buffers, and a naive configuration will hold your carefully-flushed Server-Sent Events events or chunked stream until its window fills — streaming endpoints need compression disabled or explicitly flush-aware, or your real-time API quietly becomes a batch one (see Streaming APIs: Partial Data as a Contract). Security: compressing responses that mix attacker-influenced input with secrets enables BREACH-style side channels, where an attacker measures compressed sizes to extract the secret. The practical rule for APIs: fine to compress; do not reflect attacker-controlled strings alongside secrets (CSRF tokens, session material) in the same compressed body.