Content Negotiation Explained: How Clients and Servers Agree on a Response Format
The same URL can hand back JSON to one caller, XML to another, and a French-language page to a third, without any of them needing a different endpoint. That flexibility comes from a handful of request headers most developers only half-notice.
Published July 6, 2026Content negotiation is the mechanism by which a client tells a server what representations it can handle, and the server picks the best match from what it's able to produce. It happens on a single URL: /api/users/42 doesn't need to become /api/users/42.json and /api/users/42.xml as separate routes, because the client's Accept header already says which one it wants.
GET /api/users/42 HTTP/1.1
Accept: application/jsonQuality values: expressing a ranked preference, not just a list
A client can list several acceptable formats and rank them, using a q value between 0 and 1 attached to each option:
Accept: application/json, application/xml;q=0.8, text/plain;q=0.5Here the client is saying JSON is strongly preferred, XML is acceptable as a fallback, and plain text is a distant third choice. A value with no explicit q is treated as q=1.0, the maximum. The server is supposed to pick the highest-ranked option it's actually capable of producing — if it can't do JSON at all for some reason but can do XML, it should return XML rather than erroring out, since the client already signaled that was acceptable.
The same mechanism works for language and encoding
Accept-Language follows an identical pattern for choosing which translation of a page to serve:
Accept-Language: fr-CA, fr;q=0.9, en;q=0.5This says Canadian French is preferred, any French is a strong second choice, and English is an acceptable fallback if neither French variant is available. Accept-Encoding uses the same quality-value syntax to negotiate compression, letting a client say it prefers Brotli but will accept gzip if that's all the server offers. All three headers — format, language, encoding — are answering the same underlying question in different dimensions: given several options, which is best for this particular request.
Server-driven versus agent-driven negotiation
What's described above, where the server picks based on the client's stated preferences and returns a single response, is server-driven negotiation, and it's what almost every real API and website uses. A less common alternative, agent-driven negotiation, has the server return a list of the available representations and let the client make a second request for the specific one it wants. It's rarely used in practice because it costs an extra round trip for something server-driven negotiation usually resolves in one, but it exists in the HTTP spec for cases where the server genuinely can't guess well from the headers alone.
The header that makes negotiated responses cacheable at all
A cache sitting between the client and server — a CDN, a shared proxy — has a problem with negotiated responses: the same URL can legitimately return different bytes depending on the request headers, but a naive cache keys purely on the URL and would happily serve a French response to someone who asked for English. The Vary header fixes this by telling caches which request headers were used to select the representation, so the cache includes those headers in its cache key too:
Vary: Accept, Accept-LanguageForgetting to set Vary correctly on a negotiated endpoint is a well-known way to end up with a CDN confidently serving the wrong language or format to visitors, because it cached the first response it saw for that URL and has no idea the response depends on anything beyond the URL itself.
Where this shows up day to day
Most REST APIs support content negotiation more narrowly than the full spec allows — typically just JSON, sometimes with an XML fallback for older integrations, rather than genuinely negotiating across many formats. Where the mechanism earns its keep most visibly is internationalized websites, where Accept-Language lets a server pick a sensible default locale for a first-time visitor before any explicit language preference has been set in a cookie or account setting.
Why negotiated defaults are still worth overriding explicitly
Relying purely on Accept-Language for every visit has a real downside: browsers derive it from operating system and browser settings, which don't always match what a visitor actually wants to read in. Someone using an English-language operating system while traveling, or a multilingual user who just prefers a different language for this particular site, gets stuck with whatever the header implies unless the site also offers an explicit language switcher that overrides the negotiated default and remembers the choice, typically in a cookie, for future visits. The negotiated header is a reasonable first guess for a first-time visitor, not a decision that should be impossible to change afterward.
Status codes tied specifically to negotiation failures
When a server genuinely cannot produce any representation the client says it will accept, the correct response is 406 Not Acceptable — distinct from a generic 400, because the request itself was well-formed, it's just that no available representation satisfies the client's stated constraints. In practice this status code is rare in the wild, because most servers are built to ignore an unsatisfiable Accept header and return their default representation anyway rather than failing outright, on the reasoning that a client getting something usable is more helpful than a client getting a technically-correct error with no body it can use. Whether to honor 406 strictly or fall back gracefully is a real design decision worth making deliberately rather than by default.