Content-Location
Description
The Content-Location
response header indicates an alternate location for the returned data. It provides the URI of a resource that is either a direct representation of the requested resource, an alternate representation, or a resource that contains a subset or superset of the requested resource.
This header is particularly useful in scenarios where the resource can be accessed through multiple URIs, or when the server responds with a representation that differs from what was directly requested. It helps clients understand where the returned representation can be found at a later time, or where it originally came from.
Content-Location
differs from the Location
header in that Location
typically indicates the target of a redirect, while Content-Location
provides supplementary information about the content's origin or alternate location without implying a redirection.
Syntax
The syntax of the Content-Location
header follows this structure:
<url>
: An absolute or relative URL where the returned representation can be found.
Example Syntax
This example indicates that the returned representation can also be found at /index.html
.
This example provides an absolute URL where the same representation can be found.
Examples
Basic Example
A response where the same content can be accessed through an alternate URL:
HTTP/1.1 200 OK
Date: Mon, 02 Jun 2025 19:00:00 GMT
Content-Type: text/html
Content-Location: /en/index.html
Content-Length: 1234
<!DOCTYPE html>
<html>
<head><title>Welcome</title></head>
<body>Welcome to our website!</body>
</html>
In this example, the content is returned in response to a request, but the server indicates that the same content can also be accessed at /en/index.html
.
Content Negotiation Example
A response after content negotiation, indicating the specific variant that was selected:
GET /document HTTP/1.1
Host: example.com
Accept: application/json
HTTP/1.1 200 OK
Date: Mon, 02 Jun 2025 19:10:30 GMT
Content-Type: application/json
Content-Location: /document.json
Vary: Accept
Content-Length: 76
{
"title": "Document Title",
"content": "This is the document content."
}
In this example, the client requested a resource at /document
and expressed a preference for JSON. The server responded with JSON and used Content-Location
to indicate that this specific representation is also available at /document.json
.
Resource Transformation Example
A response where the server has transformed the requested resource:
GET /data.xml HTTP/1.1
Host: example.com
Accept: application/json
HTTP/1.1 200 OK
Date: Mon, 02 Jun 2025 19:20:45 GMT
Content-Type: application/json
Content-Location: /data.json
Content-Length: 123
{
"name": "Example Data",
"values": [1, 2, 3, 4, 5],
"active": true
}
In this example, the client requested an XML resource but indicated a preference for JSON. The server converted the XML to JSON and used Content-Location
to indicate the URL of the JSON version.
Summary
The Content-Location
response header provides valuable information about where the returned representation can be found, helping clients understand the relationship between the requested URI and the returned content. This header is particularly useful in scenarios involving content negotiation, multiple representations of the same resource, or resource transformations. By using Content-Location
appropriately, servers can improve the discoverability and accessibility of their resources, enabling clients to better understand and navigate the available content.