Benedict's Soapbox


The term REST is one of the most overused and little understood terms in development (‘design’ and ‘architect’ are high up the list too). REST is hard to define because it’s not a technology - it’s more like a macro design pattern. Conversely SOAP systems are easy to identify - if you transmit data using the SOAP XML schema then it’s a SOAP system. Due to the black and white nature of populist discourse, SOAP and REST are pitched as being competing technologies and the only options. This leads to the erroneous rationale that if something is not SOAP then it must be REST. Wrong!

I have seen very few truly RESTful web services. Many purport to be ‘REST APIs’ but they are in fact more closely related to SOAP. SOAP is a Remote Procedural Call (RPC) system and these ‘REST’ systems are in fact RPC systems.

The primary currency in RPC systems are the methods. An RPC system is defined by the methods it exposes. For example, to remove an element from a collection in an RPC system, you would define an endpoint that accepts messages and then specify a method that identifies the collection and the element. The HTTP request would look like this:

GET /api?method=deleteElementFromCollection&elementId=123&collection=abc Host:

In a REST system the primary currency is the data the system exposes. There are only a handful of methods and all URI’s in the system respond to some (or all) of the methods. These are the only methods the system responds to and they cannot be augmented. In HTTP the methods are GET, POST, PUT or DELETE (and OPTIONS, HEAD, TRACE and CONNECT but they’re not significant to this discussion). The power of a REST system is in the organisation of the data, not in the methods used to manipulate the data. To remove an element from a collection in a RESTful system you would simply send a message with the DELETE method to the element. The HTTP request would look like this:

DELETE /collections/abc/elements/123 Host:

There are many other aspects which characterise a RESTful system, but this is main difference between RPC and REST. The underlying theory to web based RESTful systems is that the HTTP protocol is very capable. Learn how HTTP really works - don’t reinvent the wheel. (I believe that RPC systems bare significant similarity to procedural paradigm and are thus easy for programmers to grok).

If you really want to understand REST (which you should do if you work with the web) I strongly recommend reading RESTful Web Services by Leonard Richardson and Sam Ruby.

Update (17 March 2011): Jens Alfke made a similar rant to this - Dudes, this is so not REST. I’ve posted a few comments over there which may be of interest.