Search result caching

Saved searches

When searching using the PUT method, the query parameter save=true can be used save the query and request parameters for later retrieval. This can be used to improve performance for queries that are performed frequently, as the saved search endpoint supports conditional GET using ETag.

The response will then have status 303 See Other and Location header, from where the search result can be fetched. The URI from the Location header supports the ETag and If-None-Match headers for GET requests. GET requests to the location URI without the If-None-Match header with return the search result with it’s ETag, or 404 if the saved search has been invalidated and removed.

For item or collection search, the saved search will be invalidated and removed if any entity of that type is re-indexed.


The ETags returned from saved search requests are weak ETags; meaning that the “Content-Type” headers and query parameters won’t affect the value of the ETag.

digraph finite_state_machine {
    node [shape = point] start;
    node [shape = box, width=3];
    SEARCH [label = "PUT /search?save=true\nPUT /item?save=true\n..."];
    303 [label = "  HTTP/1.1 303 See Other\l  Location:{loc-uri}\l",margin=0.3,width=2.5];
    CONDITION[shape=diamond, label = "", width=0.3, height=0.3];
    304 [label = "  HTTP/1.1 304 Not Modified", width=2.8]
    404 [label = "  HTTP/1.1 404 Not Found", width=2.8]

    start -> SEARCH;
    SEARCH -> 303;
    303->200[label = " GET {loc-uri}\l" ];
    200->CONDITION[label = " GET {loc-uri}\lIf-None-Match: W/\"7c876b7e\"\l" ];
    CONDITION->404[label = "ETag changed         "];
    CONDITION->304[label = "ETag not changed" ];
    200->404[label = " GET {loc-uri}\l \/\/ Without header\l"];
    200->404[label = " GET {loc-uri}\l \/\/ Without header, for the second time\l"];


An item search request is first made using save=true:

PUT API/item?save=true
Content-Type: application/xml

<?xml version="1.0" encoding="utf-8"?>
<ItemSearchDocument xmlns="">
HTTP/1.1 303 See Other
Location: http://localhost:8080/API/item/saved/f8297c9d02083d66731b4438415fd26b?type=ITEM

Then, to fetch the query results:

GET http://localhost:8080/API/item/saved/f8297c9d02083d66731b4438415fd26b?type=ITEM
HTTP/1.1 200 OK
Content-Type: application/xml
ETag: W/"50521d364314765d9f672279375939b8"

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ItemListDocument xmlns="">
  <item id="VX-26424" start="-INF" end="+INF">
    <timespan start="-INF" end="+INF"/>

After that, the ETag can be used to perform a conditional GET:

GET http://localhost:8080/API/item/saved/f8297c9d02083d66731b4438415fd26b?type=ITEM
If-None-Match: W/"50521d364314765d9f672279375939b8"
HTTP/1.1 304 Not Modified