Content Negotiation

A single URL can have more than one representation. The resource /products/42 might exist as JSON for an API client, as HTML for a browser, in English or French, and gzip compressed or not. Content negotiation is the agreement between client and server about which of those representations gets returned, without changing the URL.

The client drives the request side. It sends headers that rank what it can handle: Accept lists media types (application/json, text/html), Accept-Language lists languages (en-US, fr), Accept-Encoding lists compression schemes (gzip, br), and Accept-Charset lists character sets. Each value can carry a quality weight from 0 to 1 written as q, so a client can say it prefers French but will accept English with Accept-Language: fr;q=1.0, en;q=0.5.

The server inspects those headers, decides which representation best fits, and answers with Content-Type, Content-Language, and Content-Encoding describing exactly what it sent. It also adds a Vary header listing the request headers it used to decide, which is what tells caches like Cloudflare or a CDN that the response changes based on those headers.

The common form is server-driven negotiation. The server reads the Accept family of headers, compares them against the formats it can produce, and selects the highest scoring match. If a client sends Accept: application/json, text/html;q=0.9, the server returns JSON because it scored higher. Frameworks make this routine: Spring uses @RequestMapping with produces, Express checks req.accepts, and Rails uses respond_to blocks.

When the server cannot satisfy any acceptable format, the correct answer is 406 Not Acceptable, though in practice many APIs just return their default format instead. If the client asks for something the server understands but cannot provide for that resource, the right code is still 406. The Vary header matters here for correctness, because a cache that ignores it could hand a French HTML response to a client that asked for English JSON.

There is also agent-driven negotiation, where the server returns a 300 Multiple Choices with a list of available representations and lets the client pick. It is rarely used because it costs an extra round trip. A practical middle ground is putting the format in the URL itself, like /products/42.json versus /products/42.xml, which sidesteps header parsing but is technically not content negotiation in the HTTP sense.

Use header-based negotiation when one logical resource genuinely has multiple equivalent forms and you want a clean, single URL. The clearest win is Accept-Encoding, where nearly every server negotiates gzip or Brotli compression transparently and cuts response size by 60 to 80 percent for text. Accept-Language is the other strong case, letting one endpoint serve localized content based on the browser's language settings.

The trade-offs show up with caching and debugging. A response that varies on Accept is harder to cache because the cache key must include that header, and an overly broad Vary, such as Vary: User-Agent, can fragment your cache into thousands of near-identical entries and tank hit rates. Negotiation is also invisible in a URL, so two people hitting the same link can get different content, which makes bug reports harder to reproduce.

Many API teams deliberately avoid Accept-based format switching and instead version through the URL or a custom header, because explicit is easier to test and document. GitHub's API, for example, uses Accept to select both the response media type and the API version with values like application/vnd.github+json. Compression negotiation, by contrast, is almost always worth keeping on.

A browser requests a news article and sends Accept: text/html, Accept-Language: es-MX, es;q=0.9, en;q=0.5, and Accept-Encoding: gzip, br. The server has the article in Spanish and English and can compress with both schemes.

It picks Spanish because es-MX outranks English, renders HTML, and compresses with Brotli since the client listed it. The response comes back with Content-Type: text/html; charset=utf-8, Content-Language: es-MX, Content-Encoding: br, and Vary: Accept-Language, Accept-Encoding.

The Vary header tells the CDN in front of the origin to store separate cached copies keyed by language and encoding, so an English request or an uncompressed request does not get served the Spanish Brotli copy by mistake. The browser, seeing Content-Encoding: br, decompresses the body before rendering. All of this happened against one URL with no query string and no path suffix.