Doug Hellmann

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.