There has been quite a lot of discussion on mailing lists that I am on about what it means to be RESTful. It has occurred to me that the reason for many of these discussions is that people only hear tidbits about REST and therefore draw wrong conclusions about it. Here is my understanding:

Representation State Transfer (REST) was introduced in 2000 by Roy Fielding, who is one of the authors of the HTTP specification. It is an architectural style for the web (or distributed hypermedia systems) which dictates how clients will access your application. It puts the method information in the HTTP method and the scoping information in the URI. There are commonly 4 questions that REST allows a client to ask your application:

  1. can you please GET me the REPRESENTATION for THIS_RESOURCE from your application
  2. can you please PUT THESE_VALUES for THIS_RESOURCE into your application
  3. can you please DELETE THIS_RESOURCE from your application
  4. can you please POST THIS_MESSAGE so THIS_RESOURCE can handle it.

The GET request is idempotent and should not change anything on the server; it is a read-only action. Ideally, these requests should be cachable so that your application benefits from the architecture of the web. Your PUT and DELETEs should be idempotent, which means that it doesn’t matter how many times you send an identical request, the result is always the same as if you only sent down a single request (excluding concurrency issues). The idempotent nature is important as this allows you to have stateless servers. GET and PUT are not Yin/Yang messages - just because you PUT a certain message to a resource, does not mean that you will get that same message back on a GET.

You will notice that unlike many other articles, I have not mentioned or related the verbs to CRUD. This is important to note, as it is something which I think confuses people. The REST representation of the resources dictate how the client would like to view the data, not how the server should manipulate or store that data. Like any good contract, it does not ask you to reveal its internal structure, so long as you satisfy the request. (Note: REST works really well with consumer-driven contracts).

Resources A resource can be anything that is of interest to you. For instance, you might have a resource for a Book, for an author, for many books or for the collection of all authors and all books available. Resources are addressed by unique URIs. Ideally, for humans, you want your URIs to be logical and guessable ie a URI for a specific author would be /author/{authors_name} a URI for all authors would be /author a URI for all the books written by a specific author would be /author/{authors_name}/books. Contradictory to this, it is also good to treat URIs opaquely and therefore you can’t assume a hierarchical nature, eg ISBN is a classic opaque non-hierarchical URN. The more we support this, the more interconnected our websites can be; imagin searching for ISBN:0321125215 and getting all the results from Amazon, Waterstones, eBay and Borders. This is the vision of the semantic web.

Representations A representation is nothing more that a view of a resource. Kind of like shining a light on a cone, depending upon where the spotlight is shining, you may get a circle, an ellipse or a triangle. It does not take away from the fact that the object is actually a cone. And just as shining a spotlight on a cone is like the response of a GET request, the message sent by POST needs specify only parts of the object, perhaps the height of the triangle, or the circumference of the circle.

Jim Webber, Ian Robinson and Savas Parastatidis have written a nice article on how to GET a cup of coffee that I recommend reading.