REST and YOU Part 1 – Conditional GET Requests
If you’re relatively new to REST, or have only briefly dabbled in ASP.net Web API then you’re probably not familiar with Conditional GET Requests. As the name suggests, a RESTful service should only respond with content to a conditional GET under certain circumstances. This is useful for situations where we already have a copy of a resource at the client, and may risk wasting time and bandwidth if the resource has not changed. Conditional GET requests therefore play a key role in client side caching of resources.
If conditions for the GET request are met, then the resource should be returned in the response content, with an Http 200 (OK) status code. If conditions are not met then no content should be returned, and the Http Status code should be 304 (Not Modified)
In both cases a truly RESTful service should also return at least one of two response headers, “ETag” (short for Entity Tag) and “Last-Modified” (date the resource was last modified). These two values form the basis for evaluating conditional requests. In simple terms, the Entity Tag is the result of a hash function based on the current state of the resource.
A GET request will be considered conditional if it contains either of the following request headers (Important note: this list is incomplete but I have excluded the others here for simplicity please refer to the http specification for the full list):
- If-Modified-Since (only send response if resource was modified since a certain time)
- If-None-Match (only send response if the ETag of the current resource does not match the local copy)
The first relates to the Last-Modified date. The second relates to the Entity Tag (ETag) of the resource. For example if we make GET request to our service with the header If-Modified-Since = “Tue, 20 Nov 2012 19:43:31 GMT” then we would expect a response code 200 if the resource has been modified since that date, otherwise we would expect a 304. Likewise if the ETag differs from the copy at the client.
Now this is all well and good, but so far it’s just theory. In my next post I will look at how this can be implemented on the server using Asp.Net Web API and the wonderful CacheCow framework, and consumed by an HTML5\Javascript application using jQuery.
References:
http://en.wikipedia.org/wiki/List_of_HTTP_header_fields
http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html#sec9.3
http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.25
http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.26
roysvork 