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.