INTERNET FUNDAMENTALSAI-REVIEWED

What is HTTP content negotiation?

Useful first: HTTP · optional, not a requirement

Choose your depth

Stay with the essentials, or look closer.

Simple explanation
2 min read · estimate

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]
THE IDEA TO KEEP

Content negotiation helps choose among representations; it does not promise that every requested version exists.

ONE THING TO WATCH OUT FOR

Every visitor to the same URL must receive identical content.

A server can select different representations at one URL, including different formats or languages.

A QUICK CHECK, NOT A TEST
A museum has an English guide but no Spanish version. What does sending a Spanish language preference do?
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.

Progress is saved only in this browser.

KEEP EXPLORINGHTTP
Was this explanation clear?
Report a mistake by email
Basic explanation
3 min read · estimate

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/json

When 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/plain

This 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.

[3] [5]
THE IDEA TO KEEP

Read Accept for what is requested and Content-Type for what the message contains.

ONE THING TO WATCH OUT FOR

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.

A QUICK CHECK, NOT A TEST
An app uploads JSON but wants a plain-text response. Which pair expresses that intent?
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.

Progress is saved only in this browser.

KEEP EXPLORINGHTTP
Was this explanation clear?
Report a mistake by email
Advanced explanation
3 min read · estimate

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.6

Here, 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-Language

Vary 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]
THE IDEA TO KEEP

Interpret the specific preference, identify the cache variant, and verify what the server actually returned.

ONE THING TO WATCH OUT FOR

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.

A QUICK CHECK, NOT A TEST
For Accept: text/*;q=0.8, text/html;q=0, application/json;q=0.6, what is HTML’s weight under the client’s 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.

Progress is saved only in this browser.

KEEP EXPLORINGHTTP
Was this explanation clear?
Report a mistake by email
GO STRAIGHT TO THE SOURCE

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.

  1. MDN — Content negotiation
  2. MDN — Accept
  3. MDN — Accept-Language
  4. MDN — Content-Type
  5. MDN — Content-Language
  6. RFC 9110 — Content negotiation fields and quality values
  7. MDN — Vary
  8. MDN — 406 Not Acceptable
  9. MDN — HTTP caching: variants and cache policy
How explanations are prepared