RESTful Web Services, by Leonard Richardson and Sam Ruby, was published this month. I interviewed the authors yesterday for an upcoming ITConversations show, but I also want to spell out here why I think it’s such an important book.

In the realm of IT you could hardly pick a more controversial topic. Or, in a way, a more unlikely one, given that the REST (Representational State Transfer) architectural style has its roots in what would normally have been an obscure Ph.D. thesis. Roy Fielding, the author of that thesis, told me in an interview that he was surprised by its breakout popularity. But he probably shouldn’t have been. There are not many technologies as foundational as the Hypertext Transfer Protocol (HTTP), whose principles that thesis defines.

But Fielding’s thesis is a thesis, not a practical guide. The effort to bridge from theory to practice has produced a considerable amount of folklore. “We’re writing a book,” the authors say in their web introduction, “to codify the folklore, define what’s been left undefined, and try to move past the theological arguments.” The mission is clearly defined in the first chapter:

My goal in this book is not to make the programmable web bigger. That’s almost impossible: the programmable web already encompasses nearly everything with an HTTP interface. My goal is to help make the programmable web better: more uniform, better structured, and using the features of HTTP to greatest advantage.

The book opens by usefully distinguishing between a set of architectural styles (REST, RPC [remote procedure call], REST-RPC hybrid) and suite of technologies (HTTP, XML-RPC, WS-*, SOAP). We tend to conflate architectures with technologies because they usually go together, but that’s not necessarily the case. The authors cite Google’s SOAP API (and other “read-only SOAP and XML-RPC services” as being “technically REST architecture” but nevertheless “bad architectures for web services, because they “look nothing like the Web.”

This book asserts that most services can, and should, “look like the Web,” and it spells out what that means. Among the key principles:

  • Data are organized as sets of resources
  • Resources are addressable
  • An application presents a broad surface area of addressable resources
  • Representations of resources are densely interconnected

To illustrate these principles, the authors work through a series of examples from which they distill gems of practical advice. When designing URIs, for example, they recommend that you use forward slashes to encode hierarchy (/parent/child), commas to encode ordered siblings (/parent/child1,child2), and semicolons to encode unordered siblings (/parent/red;green). Pedantic? Yes. And bring it on. Lacking a Strunk and White Elements of Style for URI namespace, we’ve made a mess of it. It’s long past time to grow up and recognize the serious importance of principled design in this infinitely large namespace.

Here’s another key principle: “When in doubt, model it as a resource.” To illustrate that principle in a dramatic way, the authors apply it to a problem that RESTful web services are normally thought incapable of solving: transactions. By modeling the transaction itself as a resource, they arrive at the following:

First I create a transaction by sending a POST to a transaction factory resource:

POST /transactions/account-transfer HTTP/1.1

The response gives me the URI of my newly created transaction resource:

201 Created
Location: /transactions/account-transfer/11a5

I PUT the first part of my transaction: the new, reduced balance of
the checking account.

PUT /transactions/account-transfer/11a5/accounts/checking/11 HTTP/1.1


I PUT the second part of my transaction: the new, increased balance of
the savings account.

PUT /transactions/account-transfer/11a5/accounts/savings/55 HTTP/1.1


At any point up to this I can DELETE the transaction resource to roll
back the transaction. Instead I’m going to commit the transaction:

PUT /transactions/account-transfer/11a5 HTTP/1.1


I don’t think my bank’s going to be adopting this technique any time soon, but it’s a fascinating thought experiment which suggests that what the authors call resource-oriented architecture (ROA) is a young and in many ways still relatively unexplored discipline.

On the question of ROA versus SOA (service-oriented architecture), the authors say that for certain kinds of enterprisey problems — including advanced security protocols and complex coordinated workflows — only SOA meets the need. They recommend it for these purposes, when the need arises. But in the many situations where the need does not arise, they recommend starting with ROA.

I’m inclined to agree, but I’d feel better about that recommendation if the glide path from ROA to SOA were smoother. It isn’t. Toward the end of our interview I asked Sam Ruby, who has been a long and forceful advocate for a smooth glide path, whether he thinks we’ll achieve it. He doesn’t. That worries me, but I haven’t given up hope. I’ve always seen ROA and SOA as points along what Frank Martinez calls a tolerance continuum. Among its other accomplishments, this excellent book advances that important point of view.