ReST in Practice

A little while ago I wrote a post about ReSTful web services and how they are distinct from a typical “HTTP done right” web service.  I have heard complaints that the characteristics of a ReSTful web service (a given resource will have links to related resources which can be used by the client as state transitions) are only applicable when the client using it a web browser, and that therefore they are more applicable to web interfaces than web services.

While it is true that it was web sites developed for browser based clients that Roy Fielding was originally describing, a web browser is far from the only client that can benefit from this type of web service.  Any sort of generic client or client library will benefit from being able to resolve transitions from just looking at the resource.  One obvious example most software engineers working with a ReSTful web service will quickly recognize the value of are browser plugins such as Chrome’s ReST Console, which allow you to browse the web service (including navigating links to related resources/states).  But there is a much more clear example of a use of ReST staring  most of you in the face.

I’m of course talking about RSS/Atom feeds.

Different content providers use completely different url schemes for their articles.  For instance WordPress blogs use a url like this:

• https://standardout.wordpress.com/2012/04/14/what-does-rest-really-mean/

Specifically the date (In /YYYY/MM/DD format) followed by the blog title.  An unfortunate scheme it turns out if something in there has to change (in the above mentioned link, I had actually published the post in June, but for some reason WordPress gave it an April date.  Then when I tried updating the publish date, the link was suddenly broken).

The Wall Street Journal uses the format

• http://online.wsj.com/article/SB10001424052702303933404577505080296858896.html

Just some long id that probably links to something in their database (nothing to show you the article is about 3D printing airplanes (wait, let me finish my post before you go to that link, it won’t be too long!)).

And then the Washington Post went with the format

• http://www.washingtonpost.com/business/technology/googles-nexus-7-teardown-shows-it-nets-a-profit–but-a-small-one/2012/07/13/gJQAFZMZiW_story.html

I guess they wanted both an unique id and a contextual id (I’m presuming they have better editors than me to make sure typos don’t make it in there).

So if you were a fan of my blog, the Wall Street Journal, and the Washington Post, can you build an application the syndicated news from all three sources?  Would you need to handle three different url patterns to deal with three different web service designs?

Of course not, thanks to the fact that all three are going to have RSS/atom feeds.  These feed formats (admittingly there are several competing formats, including atom and the many versions of rss, but much fewer than the number of sources that use them) have a standard way to link to the article, to describe the context, include pictures, authors, etc.  Thus any feed reader that knows how to parse this format can syndicate news from a huge number of providers.

These feeds are so common, we tend to refrain from calling them web services (they’ve certainly been around since before ReSTful web services were the hot new thing in software development).  But not only are they web services, they are web services designed to be used by automated clients that track the news and display articles in news tickers or web page mashups or email clients or whatever.  And they benefit tremendously from having the atom/rss resources including not just content about the article, but an actual link the to the article.  If the wordpress feed just gave the date the article was published on and its title, or the Wall Street Journal feed just gave the internal id they are using, that would be enough to figure out the link if you knew their format.  But it would be much more difficult to develop an aggregator that worked on such a feed.

I think the key here is that the strength of these services come not from the url patterns (which so many seem to get so hung up on when designing web services) but rather the resource representation. A good resource representation which is independent from the web service’s implementation, and potentially independent from the webservice itself. It can become a de facto industry standard, allowing client developers to develop clients and libraries around it.

But if your resource representation lacks any sort of ReSTful syntax, it doesn’t matter how popular it is.  Developing a library around it is not enough. The consumer still has to find a way to parse your web service to get access to the resources. And no matter how much time you slave over documenting your ideal url formats (which, the First Law of Web Services dictates, if you like your url format, 80% of the rest of the world will think it is crap), that is additional work you are putting on client developers. Their lives will be much easier if you can compact the parts of your web service they need to work on to just the resource representation.

But there is one caveat to all this, your web service’s design is hardly its most important aspect. If the information your service is exposing is useful, developers will be willing to work with it, no matter how poorly designed it is. I think every software developer out there with more than a year or two of experience can point to some service or library they used that was a pain to develop against, but they still used it because it gave them data they needed. And the inverse of the above statement is also true; if the information you are exposing isn’t useful, your web service will never get used no matter how well it is designed. So if you are spending months slaving over the perfect web service, you are probably wasting time you can better spend improving the data it is serving, or delaying your entry to the market, either one of which can do a better job crippling your service much more than a bad API.

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.