Requestly is a web proxy that requires a desktop and desktop browser. Enter your email below to receive the download link. Give it a try next time you’re on your PC!
Chrome extension
Instant & lightweight. Run the Requestly right inside your browser. Design, test, and mock APIs with collections, environments, and scripts.
The HTTP No-Vary-Search response header defines how query parameters in a URL should be treated when the browser decides whether to use a cached response. It tells the browser which parameters matter for cache matching and which ones can be ignored.
In simple terms, it controls whether URLs that look different because of query parameters should be stored as separate cache entries or treated as the same resource. This helps the browser reuse an existing cached response instead of making another network request when the content returned would be identical.
Indicates that URLs will not be cached as distinct entries if the only difference between them is the order of their parameters. However, if other parameters are present, the URLs will be cached separately.
paramsOptional
This can be either a boolean value or a list of strings:
If used as a boolean (e.g., params), it signifies that URLs differing solely by their parameters will not be cached as separate items.
If it’s an inner list of space-separated strings (e.g., params=("param1" "param2")), it means that URLs which vary only by these specified parameters will not be cached as distinct entries. The inclusion of any other parameters will result in separate caching.
exceptOptional
An inner list of space-separated strings (e.g., except=("param1" "param2")). This directive specifies that URLs that differ exclusively by the parameters listed here *will* be cached as separate entries. For this to take effect, a boolean params directive must also be included (e.g., params, except=("param1" "param2")). The presence of other parameters not in the except= list will not cause URLs to be cached as separate entries.
Example
Allowing responses from URLs with differently ordered parameters to match the same cache entry:
If you have a search page that stores its search criteria in URL parameters, and the order of these parameters in the URL cannot be guaranteed to be consistent, you can use the key-order directive to ensure that responses from URLs identical except for parameter order are treated as the same for caching:
No-Vary-Search: key-order
When this header is applied to the relevant responses, the following URLs would be considered equivalent when searching the cache:
The examples below demonstrate how to control which parameters are disregarded for cache matching purposes.
Allowing responses from URLs with a different parameter to match the same cache entry:
Consider a user directory landing page, /users, that has already been cached. An id parameter might be used to display information about a specific user, for example /users?id=345. Whether this URL should be considered identical for cache matching depends on how the application behaves:
If this parameter loads an entirely new page with the user’s information, then the response from this URL should be cached separately.
If this parameter simply highlights the user on the same page and perhaps shows a data panel, then it would be more efficient for the browser to use the cached response for /users. This could lead to performance improvements when loading user pages.
If your application functions like the second example, you can make both /users and /users?id=345 identical for caching purposes using a No-Vary-Search header:
No-Vary-Search: params=("id")
Allowing responses from URLs with multiple different parameters to match the same cache entry:
Suppose you also have URL parameters that sort the list of users on the page (e.g., ascending or descending alphabetical order) and specify the UI language, for example /users?id=345&order=asc&lang=fr.
You can instruct the browser to ignore all these parameters during cache matching like so:
No-Vary-Search: params=("id" "order" "lang")
If you want the browser to ignore all these parameters *and* any others that might be present for cache matching, you can use the boolean form of params:
No-Vary-Search: params
Specifying parameters that *do* cause cache matching misses:
Imagine the application behaves differently: /users points to the main user directory landing page, while /users?id=345 points to a completely separate detail page for a specific user. In this scenario, you would want the browser to ignore all the parameters mentioned above for cache matching, *except* for id. The presence of id would cause the browser not to match the /users cache entry and instead request /users?id=345 from the server.
This can be achieved as follows:
No-Vary-Search: params, except=("id")
How to Modify Header using Requestly
Requestly is a powerful Chrome extension that allows you to modify HTTP headers, including the No-Vary-Search header. This is useful when you want to control how caching works for URLs with query parameters, especially during testing or debugging. Steps to Modify the No-Vary-Search Header:
Install and open the Requestly Chrome extension. You can find it on the Chrome Web Store.
Create a new rule: Click on “Create Rule” and choose “Modify Headers” from the list of available rule types.
Add a new header modification:
Under “Action”, select “Add” or “Override”.
In the “Header Name” field, enter No-Vary-Search.
In the “Header Value” field, enter your preferred directive (for example, key-order).
Set the URL condition: Specify the URL or pattern where this header change should apply (for example, https://your-website.com/*).
Save the rule.
Once set up, Requestly will inject the No-Vary-Search header into all matching responses. For example, using No-Vary-Search: key-order ensures that URLs with the same query parameters in different orders match the same cache entry.
You might need to modify the No-Vary-Search header to test how your caching layer handles query parameters without changing your actual server configuration. This helps you verify cache behavior, avoid unnecessary cache fragmentation, and improve overall performance before deploying changes to production.
