Is it possible to change the REST API view based on the If-Modified-Since header?

Question

I want to implement the "get changed values" feature in my API. For example, let's say I have the following REST API call:

GET /ws/school/7/student 

This gets all students in school number 7. Unfortunately, this can be a lot. Therefore, I want to change the API to only return student records that have changed since a certain time. (A use case is that the night process starts from another system to pull all students from my system into them.)

I see that http://blog.mugunthkumar.com/articles/restful-api-server-doing-it-the-right-way-part-2/ recommends using the if-modified-since header and returning the view as follows:

• Search for all students updated since the request in the if-modified-since header
• If they are, return these students with 200 OK
• If there are no students from this request, return 304 Not Modified

I understand what he wants to do, but that seems like the wrong way. The If-Modified-Since header definition ( http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.24 ) reads:

The If-Modified-Since request header field is used with the method to make it conditional: if the requested option has not been changed since the time specified in this field, the object will not be returned from the server; instead, a 304 (unmodified) response will be returned without any message body.

This seems to me wrong. We will not return a submission or 304 as specified in the RFC, but some hybrids. It seems that the client-side code (or, even worse, the web cache between the server and the client) may misinterpret the meaning and replace the local cached value when it really just needs to update it.

So, two questions:

• Is this using the header right?
• If not (and I suspect not), what's the best practice? Query string parameter?

Answer 1

This is a misuse of the header. An If-Modified-Since header is one that an HTTP client (browser or code) can be delivered to the server when requesting a resource. If the value is "I want resource X, but only if it has changed since T." Its purpose is to provide client-side caching of resources.

The semantics of your proposed use are: "I want updates to Collection X that have occurred since the time of T." This is a query for subset X. It doesn't seem like your motivation is to enable caching. Your client-side cached view seems to contain all of X, although a typical query returns only a small set of changes to X; that is, the answer is not that you are directly caching, so caching should take place in user-side custom logic on the client side.

The query string parameter is a much more suitable solution. Below {seq} will be something like a sequence number or timestamp.

 GET /ws/schools/7/students/updates?since={seq} 

On the server side. I assume that you have a sequence of updates from the beginning of your system, and a request of the above form captures the first N updates that have a sequence value greater than {seq} . That way, if the customer has ever lagged far behind and had to catch up, the results will be uploaded.