2026-09-25 · 8 min read
- http
- caching
- api
Content-Location identifies a URI for the representation enclosed in an HTTP message. It can distinguish a selected variant or identify what a write response body represents, but it is not a navigation command and does not carry the redirect semantics of Location.
Reliable use requires an explicit representation model. A field value alone does not prove that two URIs are interchangeable, grant write authority, or make a response cacheable.
Name the representation relationship
For each response, document the effective request URI, selected representation, Content-Location URI, method, status, media type, language, content coding, validators, cache directives, and Vary dimensions. State why a consumer benefits from the secondary identifier.
- Use Location for redirect or creation semantics.
- Use Content-Location only for enclosed content identity.
- Avoid redundant fields without a consumer contract.
- Keep tenant and authorization boundaries explicit.
Resolve references safely
Resolve a relative field value against the correct base URI with a standards-aware parser. Preserve percent-encoding semantics and avoid string concatenation, filesystem-style normalization, or decoding before structural parsing.
Treat cross-origin values as untrusted references. Do not automatically fetch them with user credentials, follow them from backend networks, or attach authorization intended for the original origin.
Model selected variants
When the response is selected through negotiation, align Content-Location with Content-Type, Content-Language, Content-Encoding, Vary, ETag, and cache keys. Decide whether the variant URI is directly retrievable and whether its validators are shared with the negotiated resource.
Do not let a cache collapse language, encoding, or media variants merely because their effective request URI or representation URI looks similar.
Specify write response bodies
For POST and PUT responses, say whether the body represents the target's current state, a newly created resource, an operation result, or a status document. Select status codes and Location independently according to actual method outcomes.
Caching a response to an unsafe method requires the relevant explicit semantics; Content-Location does not supply them by itself. Revalidation and later writes still require normal authorization and precondition handling.
Test intermediaries and clients
Use Flashman's URL tool for URI resolution, diff for response variants, JSON formatter for synthetic bodies, hash tool for public representation identity, and timestamp converter for cache timelines.
Cover relative, absolute, same-origin, and cross-origin values; GET, HEAD, POST, and PUT; negotiated variants; redirects; validators; revalidation; proxy rewriting; stale caches; malformed fields; browser behavior; SDKs; and rollback.