What is HTTP content negotiation?
Useful first: HTTP · optional, not a requirement
Choose your depth
Stay with the essentials, or look closer.
YOUR GOALUnderstand why the same address can return different formats or languages.
One resource, different useful versions
Ask for the version you can use
Imagine a museum with a visitor guide available as a web page and as structured data for an app. Both describe the same guide, but each is a different representation. A server can make a choice between representations when it receives a request for the guide’s URL.
With content negotiation, the client sends preferences in HTTP headers and the server selects a response. Think of asking a desk for a particular edition of a leaflet: the request helps the desk choose, but cannot create an edition it does not have. The HTTP guide explains the request and response around that choice.
[1]A language preference is a hint
A browser can send Accept-Language to indicate preferred languages. A site with suitable translations can use that information to choose an initial version. It does not automatically translate the page.
If you explicitly select another language on the site, that choice should take priority over the browser’s language hint. A traveler might use an English-language browser while deliberately reading the museum guide in Spanish.
[3]Content negotiation helps choose among representations; it does not promise that every requested version exists.
Every visitor to the same URL must receive identical content.
A server can select different representations at one URL, including different formats or languages.
Show the explanation
Tell the server a preference, without creating a Spanish translation. The language hint can guide selection among available versions. It is not a translation service.
YOUR GOALDistinguish requested formats from returned formats and interpret a language choice.
Read the request and response headers
Accept describes a response preference
An app that wants structured guide data can send Accept: application/json. A browser requesting a page might accept text/html. These are media types, which describe formats. The request’s Accept field expresses which response types are acceptable; it does not describe a body the client is uploading.
The following is an illustrative request fragment, with other headers omitted:
GET /visitor-guide HTTP/1.1
Accept: application/jsonWhen debugging, inspect the header actually sent for that request. Browsers can use different Accept values for a page, image or stylesheet.
[2]Content-Type describes the message content
If the server returns JSON, its response can include Content-Type: application/json. When sending JSON to a server in a POST request, the client instead puts Content-Type on that request to describe its own body.
For example, an app can upload JSON while asking for a plain-text reply:
POST /visitor-feedback HTTP/1.1
Content-Type: application/json
Accept: text/plainThis fragment omits the body and other headers. Content-Type and Accept have separate jobs even when they contain the same media type. Content-Encoding describes an encoding such as compression, another separate dimension.
[4] [2]Read the audience language in the response
For a request with Accept-Language: es, en;q=0.6, Spanish has the stronger preference and English is a less preferred alternative. A server with a suitable Spanish guide may choose it.
A response carrying Content-Language: es identifies a Spanish-speaking intended audience. That header is not a language label for every sentence: a guide for Spanish speakers could contain an English quotation. In HTML, the lang attribute identifies the language of the document or an element.
Read Accept for what is requested and Content-Type for what the message contains.
Setting Content-Type: application/json asks the server to return JSON.
Content-Type describes the message’s own content. Accept expresses a preference for the response’s media type.
Show the explanation
Content-Type: application/json and Accept: text/plain The request Content-Type describes the JSON being sent; Accept asks for a text/plain reply. Server support still determines the result.
YOUR GOALInterpret media-range precedence and design for variant caching and negotiation fallback.
Handle weights, caches and unmet preferences
Specific matches determine the weight
A quality value q runs from 0 to 1; an omitted value means 1, while 0 means unacceptable. It expresses relative preference, not measured file quality. For a media type matching several Accept ranges, the most specific matching range supplies its weight.
Accept: text/*;q=0.8, text/html;q=0, application/json;q=0.6Here, HTML has weight 0 despite the broader text wildcard. Plain text has weight 0.8 and JSON has weight 0.6. This describes preferences among those formats; it does not prove the server offers them or guarantees a particular response.
[6]Keep cached variants separate
Suppose the museum uses both Accept and Accept-Language to select a cacheable guide response. It can send:
Vary: Accept, Accept-LanguageVary tells a cache which request headers influenced the response, so reuse can account for those values. Without the relevant variant information, a saved Spanish response could be reused for a request that expected another language. Use a consistent Vary value across responses for that URL, including default and 304 responses.
Vary does not itself grant permission to store a response or set its freshness lifetime; those belong to the caching policy. Only vary on inputs that matter to the selection.
[7] [9]Plan for an unsupported preference
If the server cannot supply an acceptable representation and declines to send a default, it can return 406 Not Acceptable. A server can also disregard a negotiation preference and return a default representation, so the client must not assume Accept guarantees the desired format.
For a practical failure check, imagine an app requesting JSON from a guide endpoint that only serves HTML. Check the response status and Content-Type before trying to parse a successful body as JSON. A 200 response alone does not establish that the representation matches the app’s expectation. Decide how the app will explain an unsupported response instead of treating it as valid guide data.
[8] [4]Interpret the specific preference, identify the cache variant, and verify what the server actually returned.
A broad text/* preference makes HTML acceptable even when text/html has q=0.
The more specific text/html entry determines HTML’s weight in that Accept field, so HTML is unacceptable under those preferences.
Show the explanation
0, because the specific text/html range takes precedence. The most specific matching range supplies the media type’s quality value. This determines the preference, not whether the server will honor it.
Keep asking. Check the details.
Source-checked using AI (OpenAI Codex) on . The checks covered sources, examples, and quizzes for this article version.
No human review is claimed. AI review can miss errors; check the original sources below.
- MDN — Content negotiation
- MDN — Accept
- MDN — Accept-Language
- MDN — Content-Type
- MDN — Content-Language
- RFC 9110 — Content negotiation fields and quality values
- MDN — Vary
- MDN — 406 Not Acceptable
- MDN — HTTP caching: variants and cache policy