Content-Location

The Content-Location header indicates an alternate location for the returned data. The principal use is to indicate the URL of a resource transmitted as the result of content negotiation.

Location and Content-Location are different. Location indicates the URL of a redirect, while Content-Location indicates the direct URL to use to access the resource, without further content negotiation in the future. Location is a header associated with the response, while Content-Location is associated with the data returned. This distinction may seem abstract without examples.

Syntax

Directives

Examples

Requesting data from a server in different formats

Let's say a site's API can return data in JSON, XML, or CSV formats. If the URL for a particular document is at https://example.com/documents/foo, the site could return different URLs for Content-Location depending on the request's Accept header:

Request header

Response header

Accept: application/json, text/json

Content-Location: /documents/foo.json

Accept: application/xml, text/xml

Content-Location: /documents/foo.xml

Accept: text/plain, text/*

Content-Location: /documents/foo.txt

These URLs are examples — the site could serve the different filetypes with any URL patterns it wishes, such as a query string parameter: /documents/foo?format=json, /documents/foo?format=xml, and so on.

Then the client could remember that the JSON version is available at that particular URL, skipping content negotation the next time it requests that document.