To REST Or Not

Restful mountains

HTTP is, of course, the most widely used protocol in all of computing. Very few ¬†applications use HTTP correctly or fully. I’ve designed a couple of projects recently that had the potential to use a RESTful interface. The first was a content managed web site – though the content was actually affiliate based betting offers from a variety of merchants. All fired up after a PHP London Conference lecture on using RESTful interfaces, I designed a REST interface acting on resources, fully utilising the HTTP GET, PUT, POST and DELETE verbs. It was elegant. I was proud. My lead developer loved it. The design was challenging for the rest of the development team as they lacked experience in resource-orientated architectures – which made me feel good: not only had I created a brilliant design, I was developing my team.

Needless to say implementation was less than smooth. We knew that browers don’t support PUT and DELETE very well; a bit of Javascript worked round that issue. For 80% of the site, the resource orientated architecture helped write clean, elegant code. The other 20% was extremely hard to achieve within the pure architecture. And, once you start deviating away from the principles, you then heap deviation on top of deviation and end up with some methods that will haunt you for the rest of your career.

Part of the problem with a resource orientated architecture is that your users need to think in terms of resources – web users don’t: they think in terms of pages. Squaring this circle means kludging code.

It’s possible that with more REST experience we could’ve done better. The project was completed eight months ago and we’ve had a few releases since then. There are parts of the code that are a delight to change; I’ve also looked at the deviant code to see if it could be refactored into something more elegant and supportable, and even with the extra experience, its hard to see what could have been done better.

Since completing that project we’ve designed and built a similar, though smaller and less functionally rich, web site without using REST. WE were able to take the good techniques used in the previous project and build a site that is just as easy to maintain but without any of the kludges needed to make it RESTful.

The second project was completely different. This was an API being added for an existing site to enable certain ‘trusted’ users to modify the database. The database was easily factored into resources; enabling GET, PUT, POST and DELETE made the interface concise and fluid. The users would not be using browsers, rather they access the API programmatically using anything from ColdFusion to PHP. The API made good use of HTML status codes and content types set in the header. POSTs & PUTs sent XML, GETs retreived XML. Defining the XSDs created online documentation which was immediately accessible, and just plain obvious.What started life as a complex product description turned into a few resources with XSDs to match and four verbs.

The difference between the two projects is the support offered by the client. In the first project we were limited by what browsers are capable of. And not just modern browsers: a significant, but small, number of people are still using IE6. The second project suffered no such limitation.

One of the tools we used for testing and development is the excellent RESTClient by It’s a simple client, written in Java, that allows you define headers, body, authentication and so on. You can save requests as tests making it very easy to develop a test suite.

To summarise REST works brilliantly when the client is thinking in terms of resources and can be expected to work with status codes and HTTP verbs. For a web site, though, most users will be expecting to read web pages and fill in forms rather than interact with resources. Until the next generation of browsers works with HTML verbs, and users have stopped using IE6, then REST is unsuitable for web site development.