Content-Negotiation · XB Field Notes

Accept headers let the server negotiate a reply

Tue, 23 Nov 2027 00:00:00 +0000

Negotiation selects among representations the server can actually produce. Request preferences are inputs to that decision, not evidence that the response will satisfy them. A client still needs to inspect the selected representation. Vary records the request dimensions relevant to reuse; it does not identify the chosen format, language, or compression method.

Keep the dimensions separate

Request preference	Selected representation metadata
Accept	Content-Type
Accept-Language	Content-Language
Accept-Encoding	Content-Encoding, when a content coding is applied

These dimensions are independent. Requesting JSON does not request English or gzip. Content-Language describes the intended audience’s language, not a guarantee that every character belongs to one language. A server offering English HTML and Chinese JSON cannot combine the independently preferred format and language into Chinese HTML unless that complete representation exists. Define the available combinations before deciding how to rank them.

A quality value ranges from zero to one, defaults to one, and permits at most three fractional digits. Zero means unacceptable, not merely less desirable. For media types, the most specific matching range determines a candidate’s quality. An explicit text/html;q=0 is not rescued by */*;q=1. Looking for the largest number anywhere in the field, or choosing the first comma-separated item, loses this relationship between range and candidate.

When it breaks

A missing preference field generally expresses no preference on that dimension. It is not the same input as an explicit exclusion. RFC 9110 permits a server with no acceptable representation to send 406 or disregard the field; a default response might therefore be unusable to the client. An API promising strict negotiation must define that policy itself. An exclusion communicates a constraint but does not force every deployed server to enforce it.

Different fields also have different matching rules. Accept uses media ranges; language negotiation needs a documented language-tag matching scheme; Accept-Encoding has special rules for identity, absence, and an empty value. A generic list parser cannot supply all those policies. Do not silently equate an absent field with an empty parsed collection, then conclude that the client rejected everything.

Equal weights do not establish a universal ordering rule across all servers. Make the application’s tie policy deterministic, and test it. Detailed language preferences can also expose identifying information, so neither logging complete preference profiles nor adding every possible field to Vary is automatically justified. Vary affects matching, while storage eligibility, freshness, and authorization still require their own rules.

Check it quickly

Use Python 3.11 or newer and a POSIX shell. Install the tested parser in a temporary environment, then run the Python block with "$accept_lab/venv/bin/python". Installation needs the network; the experiment itself does not send requests or start a server. It checks selection behavior in Werkzeug 3.1.8 rather than claiming to reproduce an arbitrary browser or CDN.

accept_lab=$(mktemp -d)
python3 -m venv "$accept_lab/venv"
"$accept_lab/venv/bin/python" -m pip install Werkzeug==3.1.8

from werkzeug.datastructures import Accept, LanguageAccept, MIMEAccept
from werkzeug.http import parse_accept_header

offers = ["text/html", "application/json"]
cases = [
 (None, "text/html"),
 ("application/json;q=0.9, text/html;q=0.2", "application/json"),
 ("text/*;q=0.9, text/html;q=0, application/json;q=0.5", "application/json"),
 ("application/json;q=0, text/*;q=0.4, */*;q=1", "text/html"),
 ("application/xml", None),
 ("*/*;q=0", None),
]
for header, expected in cases:
 parsed = parse_accept_header(header, MIMEAccept)
 selected = offers[0] if header is None else parsed.best_match(offers)
 assert selected == expected
 print(repr(header), "->", selected)

denied = parse_accept_header("text/html;q=0, */*;q=1", MIMEAccept)
assert denied.quality("text/html") == 0
assert denied.quality("application/json") == 1
print("specific exclusion:", denied.quality("text/html"), denied.quality("application/json"))

tied = parse_accept_header("application/json, text/html", MIMEAccept)
assert tied.best_match(offers) == "text/html"
assert tied.best_match(list(reversed(offers))) == "application/json"
print("tie: server offer order decides")

languages = parse_accept_header("fr;q=1, zh;q=0.8, en;q=0.5", LanguageAccept)
codings = parse_accept_header("gzip;q=0, br;q=1", Accept)
assert languages.best_match(["en", "zh"]) == "zh"
assert codings.best_match(["gzip", "br"]) == "br"
print("independent axes:", languages.best_match(["en", "zh"]), codings.best_match(["gzip", "br"]))

The six media results are HTML, JSON, JSON, HTML, no match, and no match. The missing-field HTML default is explicitly chosen by the caller. The two exclusion cases prove that a broader range does not override the specific candidate’s quality. The unavailable XML and universal zero cases return None; translating that result into 406 belongs to an HTTP endpoint, not this parser.

The tie test reverses the server’s offered list while leaving the request unchanged. Werkzeug follows that list when quality and specificity tie. The final checks independently select Chinese and Brotli from declared candidates; they neither create a combined representation nor perform compression. These language cases use direct tags and do not validate regional fallback. The coding check deliberately does not implement identity or missing-header semantics.

For a real integration, preserve these negative cases and inspect the actual outgoing request, returned metadata, and body. Test the default, supported alternatives, explicit exclusions, and unavailable combinations through the deployed path. Only then decide which request fields belong in Vary. A passing parser test establishes a useful component contract, not the correctness of the complete negotiation and caching pipeline.

Sources

RFC 9110: content negotiation, absence, quality values, field-specific matching, and Vary, checked 2026-09-07.
Werkzeug Accept data structures, specificity, quality, and tie behavior, checked 2026-09-07.
Werkzeug header parsing, the parser and its type-specific classes, checked 2026-09-07.

Accept plus Vary let one URL answer in several formats

Tue, 19 Jan 2027 00:00:00 +0000

One resource can have an HTML view for people and a JSON representation for programs. Sharing a URL is useful only when the origin and its intermediaries preserve that distinction. The endpoint must select an available format, serialize it honestly, describe its cache variation, and validate the selected representation rather than some other version of the same resource.

Select before you serialize and validate

For a GET response, the request’s Accept field expresses desired response media types. The request’s Content-Type instead describes request content; setting it to JSON does not ask the server to return JSON. Use the framework’s media-range parser for quality and wildcard handling. Define an explicit default for an absent Accept field, and separately define what happens when a supplied field matches nothing.

This example defaults to HTML only when Accept is absent. A supplied preference with no acceptable offer produces 406 and lists the available types. That is a deliberate endpoint policy: HTTP also allows disregarding the preference. Do not substitute 415, which concerns unsupported request content. Distinguishing these outcomes makes an API client diagnose the correct direction of the contract.

After selection, generate Content-Type from the serializer actually used. HTML data needs appropriate escaping; JSON needs JSON serialization, not string interpolation into an HTML template. Set Vary: Accept on the route’s representations, including its default. Vary does not permit storage or protect private data; the public cache directive below is appropriate only because the fixture contains the same harmless status record for every caller.

When it breaks

Testing only the origin can miss a cache serving yesterday’s HTML to today’s JSON request. Check the metadata and parsed body through the delivery path, with both request orders. A correct Vary field on new responses does not retroactively fix an already cached response whose selection metadata was missing. Use a controlled test URL or an approved invalidation procedure rather than indiscriminately flushing a shared cache.

A subtler bug uses the database row’s revision as the same strong ETag for both formats. An ETag identifies the selected representation; distinct HTML and JSON bytes cannot share that strong validator merely because they describe the same record. If conditional processing runs before format selection, the server can incorrectly return 304 for a representation the client does not hold. Select, serialize, assign the representation’s validator, then evaluate the condition.

Check it quickly

Use Python 3.11 or newer. Create the temporary environment below, then run the Python block with "$media_lab/venv/bin/python". It starts a loopback-only Werkzeug development server on an automatically allocated port and closes it afterward. Installation needs network access; the six test requests do not. This is a local protocol fixture, not a production WSGI deployment or a shared-cache test.

media_lab=$(mktemp -d)
python3 -m venv "$media_lab/venv"
"$media_lab/venv/bin/python" -m pip install Werkzeug==3.1.8

import hashlib
import html
import json
from http.client import HTTPConnection
from threading import Thread

from werkzeug.serving import make_server
from werkzeug.wrappers import Request, Response

record = {"message": "ready"}
variants = {
 "text/html": f"<!doctype html><p>{html.escape(record['message'])}</p>\n".encode(),
 "application/json": json.dumps(record).encode("utf-8"),
}


@Request.application
def application(request):
 if request.path != "/status":
 return Response("not found\n", status=404)
 if request.method != "GET":
 return Response("GET only\n", status=405, headers={"Allow": "GET"})
 media = "text/html" if "Accept" not in request.headers else (
 request.accept_mimetypes.best_match(variants)
 )
 if media is None:
 response = Response("available: text/html, application/json\n", status=406)
 response.headers["Cache-Control"] = "no-store"
 else:
 body = variants[media]
 response = Response(body, mimetype=media)
 response.set_etag(hashlib.sha256(body).hexdigest())
 response.headers["Cache-Control"] = "public, max-age=60"
 response.make_conditional(request)
 response.vary.add("Accept")
 return response


server = make_server("127.0.0.1", 0, application)
worker = Thread(target=server.serve_forever)
worker.start()


def get(accept=None, etag=None):
 headers = {}
 if accept is not None:
 headers["Accept"] = accept
 if etag is not None:
 headers["If-None-Match"] = etag
 connection = HTTPConnection("127.0.0.1", server.server_port, timeout=3)
 try:
 connection.request("GET", "/status", headers=headers)
 response = connection.getresponse()
 body = response.read()
 assert response.headers["Vary"] == "Accept"
 print(accept, "->", response.status, "bytes=", len(body))
 return response.status, response.headers, body
 finally:
 connection.close()


try:
 status, html_headers, body = get()
 assert status == 200 and body == variants["text/html"]
 assert html_headers.get_content_type() == "text/html"
 status, json_headers, body = get("application/json")
 assert status == 200 and json.loads(body) == record
 assert json_headers.get_content_type() == "application/json"
 assert html_headers["ETag"] != json_headers["ETag"]
 status, _, body = get("application/json", json_headers["ETag"])
 assert status == 304 and body == b""
 status, _, body = get("text/html", json_headers["ETag"])
 assert status == 200 and body == variants["text/html"]
 for accept in ["application/xml", "*/*;q=0"]:
 status, headers, _ = get(accept)
 assert status == 406 and headers["Cache-Control"] == "no-store"
finally:
 server.shutdown()
 server.server_close()
 worker.join()

Expected statuses are 200, 200, 304, 200, 406, and 406. The first two bodies contain the same status information in different formats, and their strong ETags differ. The third request revalidates JSON and receives no body. The fourth carries that JSON tag while requesting HTML, so it must receive HTML with 200. This is the critical negative check that a success-only format test would miss.

The final requests ask for unavailable XML and explicitly exclude every media type. Both exercise the chosen rejection policy, while no-store keeps those fixture errors out of caches. Vary is asserted on every tested response, including 304. Werkzeug supplies parsing and conditional-response handling; the example does not hand-roll header grammar or entity-tag comparisons.

Before adopting this design, ensure both serializers are part of the same resource contract and can be tested together. Distinct URLs may be operationally simpler when clients, access rules, or release schedules differ substantially. A single URL is not a reason to merge unrelated authorization rules. Whichever addressing scheme you choose, keep body verification and cross-representation validator tests in the integration suite.

Sources

RFC 9110: HTTP semantics, Accept, ETag, If-None-Match, and the distinction between 406 and 415, checked 2026-09-07.
RFC 9111: Vary matching, request matching before cached response reuse, checked 2026-09-07.
Werkzeug conditional responses, response validators and conditional body handling, checked 2026-09-07.