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:

• http://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.