Meridian Web Reference
Technical notes / Open reference
Contents ▾
GUIDE / HTTP REFERENCE

When one resource has several representations.

A resource can have several representations, but clients and caches need clear rules for selecting one.

Editorial team ·

Ask for an acceptable format

The Accept request header expresses media types a client is willing to receive, possibly with preference weights. A server can choose a supported representation or respond that it cannot satisfy the request. Not every endpoint offers multiple formats, and an absent Accept header should not be mistaken for a request to download arbitrary binary data. Document the supported choices rather than relying on a client to infer them from a URL suffix.

Use Vary for cache correctness

When the selected response depends on an incoming header, Vary tells caches which request header fields affect that selection. A response that varies by Accept should declare that relationship. Otherwise a shared cache may reuse JSON for a client expecting HTML, or the reverse. Using Vary on numerous unstable headers fragments cache entries and makes performance unpredictable. Choose negotiated dimensions only when the application has a clear reason to support them.

Distinguish language from encoding

Accept-Language expresses language preferences; Accept-Encoding negotiates content codings such as compression. These are different from the charset of a textual representation. Content-Encoding tells the receiver how to decode a transferred representation, while Content-Type identifies the media type of the resulting content. Misreading those fields can produce false debugging conclusions, such as calling compressed bytes malformed JSON before decoding them. Inspect the complete response chain.

Keep errors coherent

A server that cannot return an acceptable representation may use 406 Not Acceptable, but practical API contracts vary. Document what actually happens rather than imposing one generic pattern. Test the normal supported format, an unsupported request and an intermediary cache when relevant. When the same URI provides several representations, ensure that validators distinguish the selected response. That keeps conditional requests meaningful instead of mixing independent versions of the resource.

Keep reading

Continue with the start here index, or explore the overview for the wider context. To explore the behaviour, send a request to a controlled test server and record both its conditions and the response. Compare the result with the rule described above. An illustrative HTTP exchange should never be presented as a measurement of a remote service.