What does ReST really mean?

ReSTful web services have been popular for some time, yet still today there is confusion about what it means.  Some will say it is a web service that doesn’t use SOAP standards, others will argue it has to do with using HTTP’s PUT and DELETE methods along with their more popular siblings GET and POST, and still others will argue it has to do with an even more confusing acronym HATEOAS.  Everyone seems to have an opinion on what it means, and the only thing that is clear is that they are talking about different things.  Which is fairly ironic considering the term is an acronym for a pretty clear idea and its spelled out fairly clearly in Roy Fielding’s paper.

A lot of the problem seems to come down to ReST being marketed as the alternative to SOAP, not as simply an alternative to SOAP. As a result, any web service not using SOAP standards is assumed to be a ReSTful web service. For instance, the delicious API is often used as an example of a bad ReST API, but that really isn’t fair. Its not that it is a bad ReST API, its just not a ReST API at all. Its an RPC API, calling it ReSTful gives neither the term nor the API justice. It certainly is simpler than SOAP APIs, but that isn’t the defining characteristic of ReSTful web services.

Another web service flavor that commonly are confused for ReST are resource oriented web services (for brevity, and since this industry has a fetish for acronyms, lets call them ROWS). A resource oriented architecture is an API that is centered around doing basic functions (POST, GET, PUT, DELETE, in the HTTP vernacular, though create, read, update, delete may be more familiar to developers) around a set of resources.  This is a common feature of ReSTful web services, and is indeed a powerful notion. Proponents of RPC style services like to argue that their APIs allow them to do things more complicated that basic “CRUD” operations, but that’s only true if your resources were chosen poorly. The essential difference between the two comes down to how the web service is built up. If you build it with a simple set of resources, you need a complex set of procedures to act on them. And if you built it with a simple set of methods, you need a complex set of resources to act on. Of course you could have both a complex set of resources and procedures, but then you just end up with a convoluted mess.

So if you have a ROWS, how is that not a ReSTful web service? After all, much of the argument for ReST web services is that they use HTTP “correctly” (as opposed to RPC web services which overload GET or POST methods to implement their dozens of procedures), and a properly implemented ROWS does exactly that. But ReST does not stand for “Use HTTP correctly”, Roy Fielding is not that bad of a speller.

ReST stands for Representational State Transfer.  What the hell is that?  Exactly what it sounds like.  It means the resource’s representation contains the means for an application to change to a different state.  Think about when you are navigating a typical web page.  When you want to move to a different state in the application, you don’t usually go to your url bar and enter in a new url, or make arbitrary POST requests with a set of parameters you got from the web page documentation.  You click on a link on the current page.  Each web page (or resource, that’s what the R in URL stands for after all) contains links to take you to later states in the application.  There is only minimal need for further documentation, basically just the entry point (the home URL) and some way to interpret each resource.  The idea behind ReSTful web services is that the  same principle can be used in web services that are meant to be accessed by an application other than a web browser.  State transitions can be driven not through some hard coded set of URL patterns in the application, but by processing the resource and seeing what the valid next states are (of course with the exception of a very generic application (such as a web browser or other navigational tool), the application will still have to be coded to interpret the resource and pull out the state transition links, so something may still have to be hard coded).  So if you were accessing a social media web service and wanted to transition from the state of a person to that person’s friends, you would essentially just access the getFriends link, much as you would access a getFriends method of a Person object in an Object Oriented program.

Admittingly, most of the advantages ReSTful web services have over their SOAP brethren have nothing to do with their being ReST web services but more to do with their resource oriented nature (which is much easier to both work with and scale than RPC services) or their simplicity (even a simple RPC API like delicious’ is going to be easier to use than a SOAP based version).  ReST just brings in some structure like the SOAP standards give their respective APIs to web services that are simple and easy to use.  But if you don’t need a fully ReSTful API with links from one resource to the other, don’t feel bad about developing a ROWS or even simple RPC web service.   For a web service that is designed to be used by a single application, you probably don’t need that additional structure.  And for a web service with only one or two resources, ReST is very likely going to be overkill.  But please don’t call it a ReSTful web service.  Terminology in this industry is already complicated enough without people misusing terms like ReST.