We use analytics cookies.We use cookies to analyze site traffic and improve your experience.
Loading...
System Design and AI Engineering, by Roni Das. 984 interactive lessons.
Start LearningIntermediate · Web & Content Delivery
The process where client and server agree on the response format using HTTP Accept headers. Enables serving JSON, XML, or HTML from the same endpoint.
In short
Content negotiation is the HTTP mechanism where the client tells the server which response formats, languages, encodings, or character sets it can accept, and the server picks the best matching representation of the same resource. The client states its preferences with request headers like Accept, Accept-Language, and Accept-Encoding, and the server responds with a Content-Type and a Vary header describing what it chose.
In short
Content negotiation is the HTTP mechanism where the client tells the server which response formats, languages, encodings, or character sets it can accept, and the server picks the best matching representation of the same resource. The client states its preferences with request headers like Accept, Accept-Language, and Accept-Encoding, and the server responds with a Content-Type and a Vary header describing what it chose.
Learn it in the course
This page is the free part.
₹1,111 in India$25 everywhere elseonce, for the whole course
The System Design course covers Content Negotiation across a run of lessons, not one page. These 4 alone are about 66 minutes of step-by-step reading, every one with a quiz.
How HTTP content encoding works, negotiating compression between client and server transparently.
HTTP response headers that instruct browsers to enforce security policies.
A request timeout limits how long a client waits for a full response. Learn how to pick the value, use timeout budgets, and retry without a storm.
Resolving conflicts when offline changes sync with the server. CRDTs, last-write-wins, and merge strategies.
all part of
System Design Masterclass
770 lessons · about 287 hours · 18 free to read
₹1,111in India, by UPI
$25everywhere else, by PayPal
It is really nice and good Please join the course
You own this course
Continue with Content Encodingpay once,
yours for life
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 values like application/vnd.github+json to select the response media type, and a separate X-GitHub-Api-Version header to select the API version. 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.
GitHub API
Uses the Accept header to select both response format and API version, for example application/vnd.github+json.
Cloudflare
Honors the Vary header and negotiates Accept-Encoding to serve gzip or Brotli compressed responses from cache.
Nginx
Negotiates compression via gzip and brotli modules and uses Accept-Language with the map directive to route localized content.
Spring and Express
Frameworks read Accept headers so one endpoint can return JSON, XML, or HTML based on what the client requests.
Accept is a request header where the client lists the formats it can handle. Content-Type is a header on both requests and responses that states the actual format of the body being sent. The client uses Accept to ask, and the server uses Content-Type to answer with what it actually returned.
Vary lists the request headers the server used to choose its response, like Vary: Accept-Encoding. It tells caches and CDNs to store separate copies keyed by those headers, so a gzip client and an uncompressed client get the right version. Without it, a cache could serve the wrong representation.
406 Not Acceptable. The server returns it when it cannot produce any of the formats listed in the client's Accept header. In practice many APIs ignore strict negotiation and just return their default format instead of sending 406.
Functionally similar but technically different. A suffix like /products/42.json or a query parameter switches format through the URL path, not through HTTP headers. True content negotiation uses the Accept family of headers and keeps one canonical URL. Many API teams prefer the explicit suffix because it is easier to test and cache.
The q value is a quality weight from 0 to 1 that ranks preferences. In Accept-Language: fr;q=1.0, en;q=0.5 the client prefers French but will take English at half the priority. The server picks the acceptable representation with the highest combined score.
HTTP
The protocol powering the web. A request-response model where clients ask for resources and servers respond. Stateless by design.
REST API
An architectural style for building APIs using standard HTTP methods (GET, POST, PUT, DELETE). Resources are identified by URLs.
JSON
JavaScript Object Notation: a lightweight text format for data interchange using key-value pairs and arrays. The lingua franca of web APIs.
Content Delivery
The process of distributing and serving content to users from locations geographically close to them for faster load times.
Edge Computing
Running computation at the network edge, close to the user, instead of in a central data center. Reduces latency for real-time applications like IoT and streaming.
HTTP Caching
Browser and proxy caching controlled by HTTP headers like Cache-Control, ETag, and Last-Modified. Eliminates redundant network requests for unchanged resources.
This page explains the idea. The course covers it step by step, with diagrams. It is part of the System Design Masterclass course, which has 770 lessons. 18 of them are free to read. You pay once and keep it for life, with no subscription.
See the System Design Masterclass coursecourse 1
From absolute beginner to principal engineer, drawn step by step.
Asked about Content Negotiation in an interview?
Each question has why it is asked, a full answer, what the interviewer listens for, the follow-ups, the common mistakes and a diagram (268 diagrams in all). A PDF you keep, junior to staff level.
India: UPI, cards or netbanking through Razorpay. Elsewhere: card or PayPal. Download at once from My packs.
