The HTTPNo-Vary-Searchresponse header specifies a set of rules that define how a URL's query parameters will affect cache matching.These rules dictate whether the same URL with different URL parameters should be saved as separate browser cache entries.

This allows the browser to reuse existing resources despite mismatching URL parameters to avoid the expense of fetching the resource again, when the same content will be returned.

Syntax

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

Directives

key-orderOptional

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

paramsOptional

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 parameterswill cause them to be cached separately.

exceptOptional

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

Description

Relationship with the Speculation Rules API

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

The Speculation Rules API can also include anexpects_no_vary_search field, which indicates to the browser what the expectedNo-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 usingkey-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=3https://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=3https://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. Anid 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 aNo-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 themand any others that might be present when cache matching, you could use the boolean form ofparams:

No-Vary-Search: params

Specifying params thatdo 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 forid, 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 andVary header