I have moved my active blog over to tumblr. I've maintained this blog for reference but will be posting to http://www.robustsoftware.co.uk instead. I've pointed my Feedburner feed to tumblr so if you're subscribed already you should already have switched with me.

REST – a quick summary

I’d read a lot of blogs talking about REST and it’s benefits but I hadn’t fully got it. Whilst on holiday I read RESTful Web Services, which I had seen recommended, in an effort to try and finally grok REST.

I thoroughly recommend this book, it helped me connect a lot of previously separate ideas into a coherent whole. What I hope to do here is give an overview of what I’ve learnt from the book to act as a reference to myself and maybe help other people in the process.

Definition

REST is short for Representational State Transfer. Distilled down, it’s basically about using the HTTP verbs, GET, POST, PUT, DELETE and HEAD, in order to act on resources, represented by individual URIs.

Resources are similar to what most of you will think of as domain entities. However, a relationship between two entities can be represented by a resource.

Underlying principle

The main idea behind REST is that you are working with the HTTP protocol. Other web service ideas like SOAP, referred to in the book as Big Web Services, mostly ignore the expressiveness of the HTTP protocol and use only GET and/or POST requests. This often works against the HTTP protocol, at best it ignores .

The requests and responses of the HTTP protocol consist of a head and a body. The analogy used in the book is one of an envelope, the head being the envelope and the body being the contents of the envelope. REST uses the URI, HTTP verbs, HTTP headers and HTTP response codes in order to communicate to the server what is wanted and to the client what happened.

This is in contrast to SOAP which generally uses the URI from the head and then sends another envelope in the body to communicate more information about the request to the server and the response to the client. This is effectively putting an envelope inside another envelope.

HTTP verbs and their meanings

The beauty of the verbs are that they are mostly self-explanatory, but I’ll explain all of them for completeness.

GET

This verb means give me the current representation for the given URI. You can use headers to modify the behaviour slightly. For example, the If-Modified-Since header can be used to say “only send me the representation for the URI if it has changed since the given date”. This can be used to minimize needless traffic and processing.

DELETE

This verb means delete the representation at the given URI. There’s not really anything complicated about it.

HEAD

This is equivalent to a GET request but only returns the HEAD of the response, omitting the BODY. This is used for getting the meta data about a resource, for example checking whether a resource exists at a given URI without retrieving the BODY as well.

POST and PUT

I’ve put these two together as they are the ones I previously had most difficulty differentiating between. Needless to say the book explained the difference perfectly.

PUT is used to place a resource to a specific URI (eg. /Product/1), this can be a resource that didn’t exist before (an insert) or replace the existing representation at that URI (an update). In contrast, POST is used to add a resource to the end of a list of resources (eg. /Product) when you don’t know the URI in advance (an insert). Once you know the URI of your new resource, you will use a PUT to update it.

REST and HTML forms

A problem I had was reuse of web service code with web sites, HTML only supports the verbs GET and POST. I was concerned about having to maintain two sets of code for acting on the same resources. This can be overcome by using a concept called overloaded post.

The idea behind it is really simple, you include the verb you want to use as a query string parameter and POST to that URI (eg. /Product/1?method=DELETE). Then using some simple server-side code you handle the request as the verb passed instead of as a POST.

Conclusion

I’ve covered the main concepts that helped me understand the big picture of REST. I really think it is the best way to write web services so that they can be easily consumed by other people. The emphasis of REST is on simplicity, utilising the power of the HTTP protocol rather than building a new protocol on top of it. This goes against the common practice up until this point, which to me is a breath of fresh air.

Finally, I strongly recommend you buy the book if you are interested in learning more about REST.