The UI Case for REST

, May 26, 2007

Yesterday, I did another one of those “REST — the better Web services model” talks, which are becoming routine, but still make me think each time I do them. This time, I actually illustrated a number of concepts by using curl to access a quick (somewhat) RESTful Web app I had built with Rails, and had to think about Paul Downey’s statement that Web APIs are just Web sites.

I remembered that we had a related discussion the first time we introduced Web services in one of our client projects. The task was to build a financial application that offered both a Web UI and a B2B Web services interface, and initially, I wondered why we had to build this as two very different channels — after all, the idea was that in general, everything that could be done via the UI was supposed to be accessible via the programmatic interface, and since the Web UI was XHTML-based, it seemed obvious that there should be some way to unify the handling of Web requests and Web services requests. (After all, XHTML is just another XML-based language, and the Web services we employed were accessible over HTTP only, so the commonality was very large. Or so we thought.)

For a long time, I though what killed this idea was that this was the early Web services generation (around 2002, IIRC), so the focus was on serializing and deserializing Java objects to and from XML, and making everything appear as RPC-like as possible. When I made the switch — as most Web services proponents did — to a more document-oriented approach, I though the model would have to be something InfoPath-like: edit some huge document with an offline client, then send it to the same programmatic interface used by other applications. (BTW, whatever happened to InfoPath? Why isn’t anybody using it?)

But now I’ve come to believe that the real reason was that the interaction models were so vastly different — our Web UI, based on the Tapestry UI framework, obviously relied on HTTP for communication between browser and Web server, but it was in no way built according to REST principles. If it had been, the resources exposed through the Web UI would have been a perfect entry point for programmatic access, too.

In case you’re wondering whether there’s any point to this rambling, it’s probably this: the best way to come up with a good “API” for your Web application is to take care to design the Web UI according to REST principles first, and allow for alternative representations (i.e., alternative content types such as XML or JSON) afterwards — while you’ll almost certainly need to add some aspects and tweak some details, you’ll have a tremendous head start to a “Web service” interface that merits the name.

On May 26, 2007 10:00 PM, Keyur said:

~ the best way to come up with a good “API” for your Web application is to take care to design the Web UI according to REST principles first

Very true. If everything you expose is a “resource” there is no reason why html cannot be just another content type that you support. I think the only factor that differentiates an html representation from others is human interaction. Human interaction means you’ll probably have more state transitions from and to the html representation than others. But as long as the transitions themselves are again to other resources it’ll “just work.”