Skip to content
AITroveRead. Build. Understand.
Reading list
Make this comfortable

Content Negotiation and Compression Contracts

Last updated: 4 Oct 20266 min read
tutorial
IntermediateBy AITrove Editorial

One resource can have multiple representations: a language choice, a content type, or compressed bytes selected for a browser's capabilities. The request advertises acceptable forms; the response describes what was sent. If response content depends on a request header, shared caches need that dimension in Vary or a distinct URL. For compressed text, Content-Encoding identifies the selected encoding and Vary: Accept-Encoding protects clients that cannot decode it. Compression does not help already-compressed media much and may add CPU work. An explicit language choice in the product should remain stable rather than being silently replaced by a later header hint.

Working case

The public case-intake guide is available in English and Hindi at distinct paths. Its HTML can be compressed for capable clients, while a small image is already encoded. A proxy compresses the HTML but fails to identify the content encoding, so the browser receives unreadable bytes. Another proxy caches one compressed variant and serves it to a client that did not request that encoding. Set the response metadata with the actual bytes and vary by the request's encoding capability. Keep the locale in the path so a shared guide URL does not switch language unexpectedly during navigation.

Implementation boundary

javascript
function responseVariant(locale, encoding) {
  const language = locale === "hi" ? "hi" : "en";
  const codec = encoding === "br" ? "br" : "identity";
  return `${language}:${codec}`;
}
console.log(responseVariant("hi", "br"));
// Output: hi:br

The variant key illustrates the dimensions but does not replace HTTP headers. The server or edge must set Content-Language where appropriate, Content-Encoding for transformed bytes, and Vary for request headers that selected the representation. Keep ETags scoped to the actual representation or configure weak validation correctly; a validator for one encoding cannot blindly stand for different bytes. Test negotiation with clients that offer different encodings and with an intermediary cache turned on. Treat explicit locale routes as the stable identity and do not let Accept-Language override the user's chosen path.

Cost and boundaries

Compression reduces transfer size for text at the price of CPU time and sometimes extra caching variants. For a b-byte body, encoding work is at least proportional to b, while savings depend on repetition and chosen format. A very small response may not justify the CPU or header overhead. If k locales and c encodings are cached separately, up to k × c representations may occupy storage, though real traffic may use fewer. Measure encoded size, server CPU, first-byte delay, and decode correctness across target clients before making every response use the strongest compression setting.

Failure trace

A CDN stores a compressed JavaScript response without Vary: Accept-Encoding, then serves those bytes to an older client that did not advertise that encoding. The page fails before application code runs. Restore a correct variant key and metadata, then test through the CDN rather than only at origin. A separate bug uses the user's Accept-Language header to change an explicit /en guide into Hindi; links and page title now disagree. Honor the path selection and use header negotiation only at a documented entry route if desired.

Verification

  • A client receives only an encoding it advertised.
  • Warm shared cache retains distinct encoding variants.
  • Explicit locale routes are stable despite language-header changes.

Practice drill

Request the same public HTML path with two encoding capability sets and inspect bytes, Content-Encoding, Vary, and ETag. Warm the edge with one variant, then request the other and verify decoding. Compare compressed and uncompressed sizes for a 47 KB text response and an already-compressed photograph, recording CPU and transfer rather than assuming equal benefit. Open an explicit locale path with a conflicting Accept-Language value and confirm the path wins. Repeat with a 304 response to inspect validator and variant consistency.

Decision note

Make the representation selection explicit in both response metadata and cache identity, then compress where the measured transfer saving merits its cost.

Common Mistakes

  • Compressing bytes without setting Content-Encoding.
  • Omitting Vary for a header-selected variant.
  • Letting a language hint override an explicit locale path.

Connected lessons

HTTP Delivery and Cache Ownership; Shared Cache Keys and Private Response Boundaries; Stale Revalidation and Versioned Purges; Critical Resource Discovery and Priority; Localized Routes and Translation Release; HTTP caching: validate a changed representation with an ETag; Image Variants and Delivery Budgets.

Apply and check

Build Project: edge cache and critical resource release and review Web Development: navigation and delivery decisions quiz.

web-tech
web-development
Storage details