Book review: RESTful Web Services

Without an occasional flash of subversive literature, corporate inertia and the superior political skills of the world's idea-squashers would have turned the world of networks and computers into a gray, authoritarian wasteland long ago.

Fortunately, we have books such as Lincoln Stein's How to Set Up and Maintain a World Wide Web Site and Running Linux by Matt Welsh and Lar Kaufman. The power of subversive books is that they let you create some useful functionality without a budget or the conventional IT politics that go with getting the budget. Put a Web site on an underused server, or a Linux install on a discarded PC.

The new great subversive computer book is here. The benefit of RESTful Web Services, by Leonard Richardson and Sam Ruby (O'Reilly and Associates, 2007) and the Representational State Transfer (REST) philosophy in general, is that REST lets you sneak a big idea, a Web API, into an existing Web project. No heavyweight libraries, nothing to call attention to yourself. "No, sir, we aren't splashing out on any of those big scary Web services here. Just finishing the Web project as ordered."

What makes REST so easy to incorporate into an already-approved Web project is that it is mostly the emergent result of several decisions that you can logically say are the right ones for your site anyway.

The rules of REST are easy to justify as part of a conventional Web project. Use URLs with logical paths to refer to different items. Don't just POST everything to one place. Use GET and POST correctly. Don't POST a search, or do a GET for an action that has consequences.

Make your application produce the correct HTTP status codes: 200 for OK, 201 if you create a new resource, 300-something for different flavors of redirect, and 404 for a 404. Read the section on HTTP status codes very carefully. Getting these right is a big win for doing test-driven development, and simple clients such as link checkers. (If you write a Web application  to report your hamster's weight, and the hamster escapes, should you return a 404?)

And finally, make the results something that a machine can parse. You don't have to invent an XML schema of your own. Valid XHTML will do. This one is also easy to justify on the grounds of testing, browser compatibility and access for the disabled.

So you don't have to get Official Permission to make a Web Service. All you have to do is get the details right, and this is where RESTful Web Service is a solid resource to help you. How do you do transactions without breaking the statelessness of HTTP? Answer: treat a transaction as a resource in itself.

Of course, no technology can, by itself, magically make your project well designed and useful. There's going to be plenty of bad REST out there, the way there are plenty of badly administered Linux boxes and bad PHP scripts. Keep the book around to help you think REST, but most important, try other people's APIs.

But even if you only read RESTful Web Services with the conventional browser-using audience in mind, you'll find lots of useful material that will help you design your Web applications for cache-friendliness and testability.