HTTP Content Negotiation
HTTP content negotiation: Accept, Accept-Language, Accept-Encoding, Accept-Charset headers, content type selection, and server-driven vs agent-driven negotiation.
How clients and servers agree on a representation: Accept, Accept-Language, Accept-Encoding and Content-Type headers, the Vary header that records dependence, and common media types from JSON and XML to multipart and form encodings.
Use it when
- You are serving more than one format, language or compression from one URL.
- You need the correct media type for a payload.
Watch out for
- Content negotiation interacts with caching: responses that vary must include a Vary header or caches may serve the wrong variant.
- Servers may ignore Accept; the response Content-Type states what was actually sent.
The data
Headers
7 rows
| Header | Direction | Description | Example | Notes |
|---|---|---|---|---|
| Accept | Request | Client specifies preferred media types with quality values (q-factor) | Accept: application/json, text/html;q=0.9, */*;q=0.8 | Server responds with Content-Type or 406 Not Acceptable if no match |
| Accept-Language | Request | Client specifies preferred natural languages | Accept-Language: en-US,en;q=0.9,es;q=0.8 | Server may return localized content or 406; often ignored in APIs |
| Accept-Encoding | Request | Client specifies supported content codings (compression algorithms) | Accept-Encoding: gzip, deflate, br | Server responds with Content-Encoding; brotli (br) offers best compression for text |
| Accept-Charset | Request | Client specifies acceptable character sets | Accept-Charset: utf-8, iso-8859-1;q=0.5 | Rarely used today; UTF-8 is de facto standard everywhere |
| Content-Type | Request/Response | Media type of the request/response body | Content-Type: application/json; charset=utf-8 | Required for POST/PUT requests with body; server must respect or return 415 |
| Content-Encoding | Response | Compression applied to the response body | Content-Encoding: gzip | Must match what client Accept-Encoding advertised; browser auto-decompresses |
| Vary | Response | Indicates which request headers affect cache key for content negotiation | Vary: Accept, Accept-Language | Critical for CDNs to cache multiple variants; missing Vary causes wrong content served |
Media types
8 rows
| Type | Use | Notes |
|---|---|---|
| application/json | REST APIs, configuration | Standard for API responses; use application/problem+json for errors (RFC 7807) |
| application/xml | SOAP, legacy APIs, RSS/Atom feeds | Still common in enterprise; use application/atom+xml for feeds |
| text/html | Web pages | Always include charset=utf-8 |
| text/plain | Plain text responses | Use for non-structured text; browser won't render as HTML |
| application/octet-stream | Binary data, file downloads | Default when type is unknown; browser triggers download |
| multipart/form-data | File uploads in HTML forms | Requires boundary parameter; use for file uploads not JSON payloads |
| application/x-www-form-urlencoded | HTML form submissions (default) | Key=value&key2=value2 format; use for simple form data, not file uploads |
| application/graphql+json | GraphQL API responses | Emerging standard; use instead of application/json for GraphQL endpoints |
Fields
The shape of this dataset, read from the data itself: every column, its type and a real value. Agents can use this to plan a query without fetching the whole document.
| Section | Field | Type | Example |
|---|---|---|---|
| headers | header | string | Accept |
| headers | direction | string | Request |
| headers | description | string | Client specifies preferred media types with qua… |
| headers | example | string | Accept: application/json, text/html;q=0.9, */*;… |
| headers | notes | string | Server responds with Content-Type or 406 Not Ac… |
| media_types | type | string | application/json |
| media_types | use | string | REST APIs, configuration |
| media_types | notes | string | Standard for API responses; use application/pro… |
Fetch the same bytes
The static files contain the same reference rows as the API, with no API rate limit. Live metadata, such as view counts, may differ. Use the API for content negotiation; use the static files for a cacheable snapshot.
curl "https://yjtoon.yunusemrevurgun.com/api/dataset/http-content-negotiation?format=toon"
const res = await fetch( "https://yjtoon.yunusemrevurgun.com/static-data/dataset/http-content-negotiation.toon" ); const toon = await res.text();
Rate limit: 120 requests per minute per IP, no key and no signup. API reference →