Book Review: RESTful Web Services

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.

PyMOTW: unittest

Python’s unittest module, sometimes referred to as PyUnit, is
based on the XUnit framework design by Kent Beck and Erich Gamma.
The same pattern is repeated in many other languages, including C, perl,
Java, and Smalltalk. The framework implemented by unittest supports
fixtures, test suites, and a test runner to enable automated testing for
your code.

Read more at pymotw.com: unittest

django-links

PyMOTW: optparse

The optparse module is a modern alternative for command line
option parsing that offers several features not available in getopt,
including type conversion, option callbacks, and automatic help
generation. There are many more features for to optparse than can be
covered here, but hopefully this introduction will get you started if
you are writing a command line program soon.

Read more at pymotw.com: optparse

feedcache 1.1

There is a new release of feedcache available tonight, based on a
patch from Thomas Perl. The update includes Unicode support for URLs, a
“force” flag to always download data, and an “offline” mode flag to
never download data.

Thanks, Thomas!

Python Developer Networking

Jesse Noller is leading a campaign to have Python developers form a
network via LinkedIn.com. He talks about it over on his blog, so
check it out for the details.

According to Doug Napoleone‘s comment on Jesse’s post, there is a
more formal effort to set up a PyCon08 group and tie it in with the web
site for the convention. I didn’t realize that LinkedIn supported
groups other than “employers”. It looks like the right way to go for
the community is a “networking group” (there are only a few types, and
the others seem to imply a more formal organization than what we would
have). Unfortunately, the groups feature is closed for right now.

For now, following Jesse’s lead, I set up a position with the “Python
community” organization and job title “None”. I had to guess at the
start date. :-)

I noticed several Python-oriented groups over on Facebook, so that
might be an alternative if LinkedIn doesn’t come through. Somehow
LinkedIn feels more professional; maybe I just have a historical bias
based on Facebook’s origins, though.

PyMOTW: csv

The csv module is very useful for working with data exported from
spreadsheets and databases into text files. There is no well-defined
standard, so the csv module uses “dialects” to support parsing using
different parameters. Along with a generic reader and writer, the module
includes a dialect for working with Microsoft Excel.

Read more at pymotw.com: csv

PyMOTW: getopt

The getopt module is the old-school command line option parser which
supports the conventions established by the Unix function getopt().
It parses an argument sequence, such as sys.argv and returns a
sequence of (option, argument) pairs and a sequence of non-option
arguments.

Read more at pymotw.com: getopt

feedcache 1.0

I am happy with the API for feedcache, so I bumped the release to 1.0
and beta status. The package includes tests and 2 separate examples (one
with shelve and another using threads and shove).