Cache-control policy for search resource on RESTful API

Question

I'm creating a RESTful API (using MVC.NET) to allow external access to a business system. The API includes a search resource. The resource takes the URI form "/example/search/pages/1/?query=something".

Example: To search for pizza you would access the URI "/example/search/pages/1/?query=pizza" which would give you the first 10 results. To get the second page of results you would request "/example/search/pages/2/?query=something" etc.

I've used the cache-control HTTP header to enable public caching of all the resources on the API with the aim of dramatically reducing the load on the server(s) serving the API web app.

However I'm not sure what caching policy to use for the search resource. As the resource (and it's URI) vary depending on what you search for, there's seems little point caching the page. What caching policy (i.e. caching via the cache-control HTTP header) do people recommend for search resources on RESTful APIs? No caching? Private caching with a very short expiry time? Public caching with short expiry?

Answer 1

public caching with an appropriate max-age is what you want for this - the value of max-age will be application specific and is a subjective judgement call you have to make.

You have to balance the risk of serving stale responses against the reward of not having to compute every request.. If this risk is extremely high then shorten the time - but just be conscious that by doing this you are increasing load of your origin server. It's a good idea to monitor usage patterns and server loads in order to establish that your initial judgement is correct.

This wasn't part of your question but if I was you I would move the pagination into the query part of the URI, so

/example/search/pages/1/?query=something

would become:

/example/search?term=something&page=1

It's not essential but it will be more intuitive for developers, and you can hit it easier with an HTML form

Answer 2

I was just about to ask a similar question. I have a question of how to define views and search views, and underlying both is the issue of a non-static resource. As I know the view contents will change at some point - in my case a list of products will contain new products one day, the previous answer does it. It's a balaned risk. If new products only appear on a daily basis then caching should expire daily. Thanks for clarifying for me mike.

Answer 3

Most proxy will not cache anything that uses a querystring.

If you want caching, I'd suggest crafting new URIs for your search request using a POST-Redirect-GET pattern.

POST search Content-Type: application/x-www-form-urlencoded

term=something

303 See Other Location: /search/something/1

This will enable caching more agressively, but you'll have to craft those URIs and will still get hit by the initial POST. That said, if it's the query that's problematic, this will solve the problem nicely.