No-Vary-Search

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.

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.

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")

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

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")