Book Review: RESTful Web Services

Originally posted · 5 min read

As part of the Atlanta Python Users’ Group Book Club, I received a copy of RESTful Web Services written by Leonard Richardson and Sam Ruby, and published by O’Reilly Media. When we started the book club, this was the first book I suggested we read. I had previously studied some material on various blogs discussing REST, but I wanted a clear description and more specific examples. The book provided both, and I highly recommend reading it before planning your next web development project.

Overview

Unlike many such books, RESTful does not depend on a single programming language for examples. Much of the code is Ruby, but Python and Java make up a respectable proportion of the material as well. Since I was primarily interested in the design principles and “theory”, I did not try to run any of the sample code myself. Others in the book club have, so check the forum for more details if you are interested in that aspect of the book.

The outline of the book follows a well thought-out progression of topics from basic “programmable web” concepts to in-depth discussion of Roy Fielding’s Representational State Transfer (REST) ideas and then Resource Oriented Architecture (ROA), a natural extension of REST. Intermediate chapters include discussions of best-of-breed tools for web development and copious example code.

Outline

Chapter 1 is a foundation chapter for the remainder of the book. It describes how the HTTP protocol works and breaks down the different architectural styles discussed in the remaining chapters (REST, RPC, and REST-RPC hybrid). The theme of this chapter, and perhaps the entire book, is that “the human web is on the programmable web”. If something is on the web, it is a service.

Chapter 2 introduces the concepts necessary to implement clients using web services. The easily digestible example code (in several languages) implements a client for the del.icio.us bookmarking service. Bookmarks are an excellent choice for an example program, since the information being managed is straightforward and everyone understands the concept, even if they have never used del.icio.us directly. Chapter 2 also includes recommendations for client tools and libraries for common languages. Basic HTTP access, JSON parsers, XML parsers (including details about DOM, SAX, and pull-style parsers and when each is appropriate), and WADL libraries are discussed, with best-of-breed options presented for each language.

In chapter 3, the authors use Amazon’s S3 service design to point out features of the REST architecture which make it different from RPC-style APIs. The complexity of the examples increases to match the requirements of the service, including advanced authentication techniques.

Resource Oriented Architecture, introduced in Chapter 4 and discussed in an extended design example used through chapters 5 and 6, is perhaps the most interesting part of the book. ROA is a set of design principles which encourage you to think about your service in a specific way to enable REST APIs. The principles are:

Descriptive URIs
URIs should convey meaning
Addressibility
Expose all information via URLs
Statelessness
The client maintains the application state so the server does not have to.
Representations
Resources can have multiple representations, based on format, level of detail, language, and other criteria
Connectedness
Link between related resources explicitly within the representations, so the client does not have to know how to build URLs
Uniform Interface
Use the HTTP methods (GET, PUT, POST, DELETE) as designed

To illustrate these principles, in chapters 5 and 6 the authors build a web mapping service, similar to Google Maps. This detailed example also serves as a way to introduce their ROA development process.

  1. Identify the data set to be managed by the service.
  2. Split up that data into resources.
  3. Name each resource with a URI.
  4. Expose a subset of the uniform interface for each resource, depending on what makes sense and what features are to be supported.
  5. Design representations to be passed from client to server.
  6. Design representations to be passed from server to client.
  7. Include links to other resources.
  8. Consider a typical course of events, to ensure completeness.
  9. Consider error conditions, to identify the HTTP response codes to be used.

Chapter 7 includes the implementation of a bookmarking service similar to del.icio.us. The sample code uses Ruby extensively, and it was a little more advanced than what I was prepared to absorb without a Ruby primer. One important point made in the prose of the chapter is that code frameworks may constrain your design by making certain choices for implementation easier or harder.

Chapter 8 is a summary of the REST and ROA principles discussed in the earlier chapters, and is an excellent reference once you’ve finished reading the whole book. It is also suitable as a “Cliff’s Notes” version of the material, if you don’t have time to read everything. If you want to review the book before reading it, go to the book store and take a look at this chapter.

While chapter 2 covered client implementation techniques, chapter 9 is a survey of tools and aspects of web service implementations in different languages. It covers topics such as XHTML, HTML5, micro-formats, Atom, JSON, RDF, control flow patterns, and WSDL.

In chapter 10, the authors give an extensive comparison of ROA and “Big Web Services” to argue that ROA is simpler, requires fewer tools, and can even be more interoperable.

Chapter 11 is the requisite “How to use this with AJAX” chapter. And the book wraps up in chapter 12 with a discussion of frameworks for doing RESTful development in multiple languages. The coverage of Django includes a dispatcher that decides how to handle the request based on the HTTP method invoked.

Conclusion

Before reading “RESTful Web Services”, I had a somewhat cloudy notion of REST and how to apply it. The book clarified what REST is and how to apply it. It also offered an invaluable concrete process to follow when implementing a web service using REST and ROA principles. I expect my copy to see a lot of use and become dog-eared as I refer back to it frequently.

PyATL Book Club

The Atlanta Python Users’ Group runs an online book club. We encourage all Atlanta area Python developers to check the schedule on PyATL.org and come down to a meeting. Anyone is free to join and participate. For more reviews by members of the book club, check out the forums or our Reviews List.