Vary
Description
The Vary response header indicates the request headers that the server uses to determine which cached version of a resource to return. This header is crucial for content negotiation, as it informs caches (browsers, proxies, CDNs) about the variables that affect the response content, ensuring that clients receive the correct variant of a resource.
When a server returns different responses based on request headers like Accept, Accept-Language, or User-Agent, the Vary header helps caches understand that these responses should be stored separately and served appropriately. Without this header, caches might incorrectly serve a cached response to a client that should receive a different variant.
The Vary header is particularly important for:
- Serving different content formats (HTML, JSON, XML) based on Accept headers
- Serving different languages based on Accept-Language headers
- Serving different versions for mobile vs. desktop clients based on User-Agent
- Serving different content based on cookies or authentication status
Syntax
The syntax of the Vary header follows this structure:
<header-name>: The name of a request header that affects the response content.- Multiple headers can be specified, separated by commas.
- The special value
*indicates that the response varies based on something that cannot be captured by request headers alone.
Example Syntax
This example indicates that the response varies based on the Accept and Accept-Language request headers.
Examples
Content Type Negotiation Example
A response that varies based on the Accept header:
GET /api/resource HTTP/1.1
Host: example.com
Accept: application/json
HTTP/1.1 200 OK
Date: Mon, 02 Jun 2025 22:00:00 GMT
Content-Type: application/json
Vary: Accept
Content-Length: 42
{"name": "Example", "value": 123}
When the same resource is requested with a different Accept header:
GET /api/resource HTTP/1.1
Host: example.com
Accept: text/html
HTTP/1.1 200 OK
Date: Mon, 02 Jun 2025 22:00:05 GMT
Content-Type: text/html; charset=UTF-8
Vary: Accept
Content-Length: 213
<!DOCTYPE html>
<html>
<head><title>Resource</title></head>
<body><p>Name: Example<br>Value: 123</p></body>
</html>
The Vary: Accept header tells caches that these are different responses that should be stored separately.
Multiple Variation Factors Example
A response that varies based on multiple request headers:
HTTP/1.1 200 OK
Date: Mon, 02 Jun 2025 22:10:30 GMT
Content-Type: text/html; charset=UTF-8
Vary: User-Agent, Accept-Language
Content-Length: 1234
<!DOCTYPE html>
<html lang="en">
<head><title>Adaptive Content</title></head>
<body>
<p>This content is optimized for your browser and language preferences.</p>
</body>
</html>
In this example, the server indicates that the response varies based on both the user's browser (User-Agent) and language preferences (Accept-Language).
Compression Example
A response that varies based on the client's supported encodings:
HTTP/1.1 200 OK
Date: Mon, 02 Jun 2025 22:20:45 GMT
Content-Type: text/css
Content-Encoding: gzip
Vary: Accept-Encoding
Content-Length: 456
[...gzipped CSS content...]
This example indicates that the response varies based on the Accept-Encoding header, which is common when servers use content compression.
Authentication State Example
A response that varies based on authentication state:
HTTP/1.1 200 OK
Date: Mon, 02 Jun 2025 22:30:15 GMT
Content-Type: text/html; charset=UTF-8
Vary: Authorization, Cookie
Content-Length: 2345
<!DOCTYPE html>
<html>
<head><title>User Dashboard</title></head>
<body>
<h1>Welcome, User!</h1>
<p>Your personalized content is displayed here.</p>
</body>
</html>
In this example, the server indicates that the response varies based on the authentication headers, preventing caches from serving authenticated content to unauthenticated users.
Summary
The Vary response header is essential for proper caching behavior in scenarios where servers deliver different content based on request headers. By explicitly indicating which request headers affect the response, this header ensures that caches correctly store and serve different variants of a resource. Without the Vary header, caching systems might serve incorrect content to users, leading to functionality issues and potentially security problems. When implementing content negotiation, compression, or personalized responses, always include the appropriate Vary header to maintain the integrity of your web application's behavior across different caching layers.