Accept Headers

## The problem it solves One URL can stand for a resource with several *representations*: `/users/42` might be renderable as JSON, as XML, or as an HTML page. Choosing among them is **content negotiation**. In the *proactive* (server-driven) form defined by RFC 9110, the client states its capabilities up front in `Accept`-family request headers and the server decides. ## Syntax `Accept` carries a comma-separated list of **media ranges**. Each range is `type/subtype` optionally followed by parameters after semicolons: ``` Accept: application/json, text/html, image/*, */* ``` `type/subtype` is an exact media type. `type/*` matches any subtype of that type. `*/*` matches anything. Ranges may also carry weights (`;q=…`) which express relative preference; weights are a topic of their own, and everything below holds when no weights are present. An absent `Accept` header means the client accepts anything — it is equivalent to `Accept: */*`, not an error. ## What the server does with it 1. Determine the set of representations it can produce for that resource (JSON only, or JSON + XML + HTML…). 2. Discard those the client did not accept. 3. Among the survivors, choose one — using the client's stated preference first, then its own preference as a tiebreaker. 4. Send the chosen representation with a `Content-Type` header that names exactly what was sent. Step 4 is the part candidates forget. The response is not self-describing without `Content-Type`; the client should read the actual `Content-Type`, not assume the server honoured its first choice. If nothing survives step 2, the server has two legitimate options — refuse with `406 Not Acceptable`, or ignore `Accept` and send its default. Which one real servers pick is a separate discussion. ## Direction matters: Accept vs Content-Type - Request `Accept: application/json` → "send me JSON back." - Request `Content-Type: application/json` → "the bytes I am sending you *are* JSON." - Response `Content-Type: application/json` → "the bytes I am sending you are JSON." There is no `Accept` header on a response. A POST commonly carries both: `Content-Type` for the body it sends, `Accept` for the body it wants back, and they need not be the same (`Content-Type: application/x-www-form-urlencoded` with `Accept: application/json` is ordinary). ## The Accept family The same request-side pattern repeats for other axes of negotiation: `Accept-Language` for natural language, `Accept-Encoding` for compression, and the obsolete `Accept-Charset`. Each has a matching response header that reports what was actually chosen — `Content-Language`, `Content-Encoding`. ## Caching A negotiated response is only valid for clients that sent a compatible `Accept`. The server signals that with: ``` Vary: Accept ``` This tells shared caches to key the stored entry on the request's `Accept` value. Omitting it is a classic production bug: the first request warms the cache with JSON and an HTML-only browser is later served that JSON from the CDN. ## What Accept is really used for in practice - **APIs** that emit JSON by default but can emit XML, CSV, or a problem document. - **Browsers**, which send a long list like `text/html,application/xhtml+xml,image/avif,image/webp,*/*` so a server can return AVIF to a modern browser and JPEG to an old one from the same URL. - **Versioned APIs** using vendor media types such as `application/vnd.example.v2+json`. ## What it is not It is not a field filter (that is a query parameter concern), not a compression control (`Accept-Encoding` does that), and not binding on the server. A server that only ever produces JSON is entitled to produce JSON regardless of what `Accept` says — many do exactly that, and clients must tolerate it.