REST and usablity shouldn't be mixed

REST is meant to allow you to represent a resource in different formats as well as provide an interface to CRUD it. If you're building REST web services, each resource will only support four operations - create, retrieve, update and delete by using http put, get, post and delete operations on a particular URL representing a resource. It should also be possible for you to navigate to http://web-service.com/resource/1.xml and be presented with an XML representation of the resource with an id of 1 while http://web-service.com/resource/1.json gives you a JSON representation and http://web-service.com/resource/1.html a HTML version of the same resource. Now, the fact that one of those formats (HTML) is human readable is incidental - yet the temptation exists to try to take this and build an interface which is usable by humans. Real cool, eh? I append .xml and I have a web service, but if I append .html I get a neat UI.

Sadly, most applications never do just one thing on a particular page. It's a usability thing - When creating a resource I want to also see the serial number of its parent resource so that <insert valid usability requirement here>. Now this requirement can't be met without polluting your REST service (doing more than just create/retrieve/update/delete with a single URL) - or you could remain a REST purist and piss all your users off.

My point is that a REST application exposes a CRUD interface, while a user application needs to expose a usable interface and you don't want to try mixing the two. If all you're doing is providing a simple, dumb interface for data entry and simple testing (and assuming the real use of your REST application is by other applications consuming services), REST based HTML interfaces may work. But a regular application should never try to exploit the fact that REST services can be rendered as HTML. Always completely separate out your services into a stand alone application and have a second, human usable application consume them. That way, the REST services remain pristine and your users get something they can use without having to bend over backwards first.

(The tendency to start using REST rendered HTML for a UI is something I've observed after a couple of months of working on assorted REST projects. This post was a result of talking to other people in ThoughtWorks who are currently on REST projects as well as a fair number of discussions with Srihari while pairing)