No-Vary-Search header

Syntax

No-Vary-Search: key-order
No-Vary-Search: params
No-Vary-Search: params=("param1" "param2")
No-Vary-Search: params, except=("param1" "param2")
No-Vary-Search: key-order, params, except=("param1")

Directives

key-order Optional

Indicates that URLs will not be cached as separate entries if the order in which parameters appear in the URL is the only difference. The presence of other parameters will cause URLs to be cached separately.

params Optional

Either a boolean or a list of strings:

• As a boolean (params), it indicates that URLs that differ only by their parameters will not be cached as separate entries.
• An inner list of space-separated strings (params=("param1" "param2")). Indicates that URLs that differ only by the listed parameters will not be cached as separate entries. The presence of other parameters will cause them to be cached separately.

except Optional

An inner list of space-separated strings (except=("param1" "param2")). Indicates that URLs that differ only by the listed parameters will be cached as separate entries. A boolean params directive has to be included for it to take effect (params, except=("param1" "param2")). The presence of other parameters that are not in the except= list won't cause URLs to be cached as separate entries.

Description

Relationship with the Speculation Rules API

The Speculation Rules API supports using the No-Vary-Search header to reuse an existing prefetched or prerendered page for different URL parameters — if they are included in the No-Vary-Search header.

The Speculation Rules API can also include an expects_no_vary_search field, which indicates to the browser what the expected No-Vary-Search value will be (if any) for documents that it is receiving prefetch/prerender requests for via the speculation rules. The browser can use this to determine ahead of time whether it is more useful to wait for an existing prefetch/prerender to finish, or start a new fetch request when the speculation rule is matched. See the "expects_no_vary_search" example for an explanation of how this can be used.

Examples

Allowing responses from URLs with differently ordered params to match the same cache entry

If you have for example a search page that stores its search criteria in URL parameters, and you can't guarantee that the parameters will be added to the URL in the same order each time, you can allow responses from URLs that are identical except for the order of the parameters to match the same cache entry using key-order:

No-Vary-Search: key-order

When this header is added to the associated responses, the following URLs would be treated as equivalent when searching the cache:

https://search.example.com?a=1&b=2&c=3
https://search.example.com?b=2&a=1&c=3

The presence of different URL parameters, however, will cause these URLs to be cached separately. For example:

https://search.example.com?a=1&b=2&c=3
https://search.example.com?b=2&a=1&c=3&d=4

The below examples illustrate how to control which parameters are ignored in the context of cache matching.

Allowing responses from URLs with a different param to match the same cache entry

Consider a case where a user directory landing page, /users, has already been cached. An id parameter might be used to bring up information on a specific user, for example /users?id=345. Whether this URL should be considered identical for cache matching purposes depends on the behavior of the application:

• If this parameter has the effect of loading a completely new page containing the information for the specified user, then the response from this URL should be cached separately.
• If this parameter has the effect of highlighting the specified user on the same page, and perhaps revealing a pullout panel displaying their data, then it would be better for the browser to use the cached response for /users. This could result in performance improvements around the loading of the user pages.

If your application behaves like the second example described above, you could cause both /users and /users?id=345 to be treated as identical for caching purposes via a No-Vary-Search header like so:

No-Vary-Search: params=("id")

Allowing responses from URLs with multiple different params to match the same cache entry

Say you also had URL parameters that sorted the list of users on the page in ascending or descending alphabetical order, and specified the language to display the UI strings in, for example /users?id=345&order=asc&lang=fr.

You could get the browser to ignore all of these when considering cache matching like so:

No-Vary-Search: params=("id" "order" "lang")

If you wanted the browser to ignore all of them and any others that might be present when cache matching, you could use the boolean form of params:

No-Vary-Search: params

Specifying params that do cause cache matching misses

Say the app behaved differently, with /users pointing to the main user directory landing page and /users?id=345 pointing to a completely separate detail page for a specific user. In this case you would want the browser to ignore all the parameters mentioned above for cache matching purposes, except for id, the presence of which would cause the browser to not match the /users cache entry and request /users?id=345 from the server.

This can be achieved like so:

No-Vary-Search: params, except=("id")

Specifications

Browser compatibility

See also

• HTTP Caching: Vary and Vary header