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 Host: example.comThe response gives me the URI of my newly created transaction resource:
201 Created Location: /transactions/account-transfer/11a5I 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 Host: example.com balance=150I 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 Host: example.com balance=250At 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 Host: example.com committed=true
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.
I see I need to add ROA to my tags now :-)
“I asked Sam Ruby whether he thinks we’ll achieve it. He doesn’t.”
That’s amazing after putting a book out there for sale.
Isn’t “RESTful Web Services” a contradiction in terms? The point is to steer clear of “Services” (verbs, procedure calls) in favour of “Resources” (nouns, URIs).
The acronym “ROA” is great – much better, and properly in spirit with the REST approach.
Here’s hoping ROA catches speed soon!
PS – shouldn’t the second example be (/parent/child1,child2) and the third example (/color/red;green)?
Jon, you say that commas should be used to encode ordered siblings in an URL, but in the example child1 and child2 are separated by a semicolon.
Note punctuation error:
commas to encode ordered siblings (/parent/child1;child2)
you have a semi in there instead of a comma
“That’s amazing after putting a book out there for sale.”
The “it” in this case refers to convergence of ROA and SOA, not to their ongoing success in different realms, and not to the success of ROA which is the subject of the book.
“you have a semi in there instead of a comma”
Fixed, thanks.
I just finished the book, reading it cover-to-cover within 36 hours. It’s excellent – concise, clear, comprehensive, with a great mix of practical information and theory, and an impressively even depth. I’ve been developing RESTful services for over 18 months, and I see the release of this book as a major milestone in the raucous development of RESTful service design. Well done!
Yes, there is a need for practical advice on REST. Many of the online discussions are detailed and academic, with as many opinions as commenters. While the various perspectives are usually valid, it doesn’t make much difference to a programmer who just wants some practical advice on the boundary questions, e.g.:
– How to expose a search function?
– How to expose a function that *does* something, not just CRUD. e.g. print a document.
– How to deliver the same resource with different response formats
– And the inevitable REST question: what to make of cookies?
You could fill a chapter on each of these, with the number of opinions around them.
This article aims to cut through the arguments and give some concrete advice on matters like these: http://ajaxpatterns.org/RESTful_Service.
Even then, there were aspects in writing it that were continually revised due to different responses from reviewers.
REST is finally gaining some mainstream acceptance and know-how due to several causes:
– Trend towards web APIs – many of them from the web 2.0 world where simplicity is valued
– Ajax builds demand for simple web services
– Rails and DHH are doing a lot to push the cause, probably to a degree that is currently under-estimated but will have a major long term impact as that is a space where many thought leaders are influenced
– SOAP fatigue
Looking forward to reading this!
ROA = Ridiculous Orientation Abstraction.
..The point is that we simply state our intent and ship all state necessary for that intent to the server. (BTW this is analogous to database LOG files… that store INTENT, not results).
The key to implementing something like this is to understand that physical HTTP Endpoints for our REST service are just wrappers around an internal endpoints that have URIs too…
Either I can put/post/get/delete accounts, or transactions, but modeling both it seems like there’s one too many. Posting on a transaction leads to a side effect, and deprecates post on accounts (to perform what?); would GET on an account still work?
That said, this approach gives an view on an important matter.
BTW, finally got the book today! Will read it carefully!
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.
This quote seems to be missing a bit of context. In the preface, the authors’ goal is stated as being one “to reunite the programmable web with the human web. We envision a single interconnected network: a World Wide Web that runs on one set of servers, uses one set of protocols, and obeys one set of design principles. A network that you can use whether you’re serving data to human beings or computer programs.” Yet the paragraphs that immediately precede the quote about making the programmable web better establish the position that the “RESTful” space of today’s Web essentially encompasses read-only sites (e.g., static web pages and search engines), and that the bulk of today’s Web Applications do not meet the criteria for RESTfulness. The unstated assertion here then is that in order to meet the authors’ stated goals, the majority of today’s Web Applications will need to be re-architected and re-written in order to conform to a RESTful style! Stated another way: the RESTful approach is essentially unproven outside of the read-only Web, yet the authors assert not only that RESTfulness will make the Programmable Web better but also that we should discard the proven ways of constructing Web Applications in favor of the RESTful approach! (I.e., the only way to have RESTful Web Services and unification of the human and programmable webs is for human-oriented web applications to adhere to the rules of RESTfulness as well!) Am I missing something, or doesn’t this run counter to the often-voiced argument that REST builds upon what makes the web what it is today?
“Am I missing something, or doesn’t this run counter to the often-voiced argument that REST builds upon what makes the web what it is today?”
I thought this was a good question. I invited the authors to respond. Leonard did, here:
http://www.crummy.com/2007/06/12/0
Thanks for the review of the book. I just heard about it somewhere else a few days back, Googled some more today and came across your review of it. (I’ve been reading your articles right from the BYTE column days and think they’re very good. Also your book “Practical Internet Groupware”.) I think REST is a good architectural style, and though, as you say, it may not fulfil all of the goals of SOA, it definitely has its place as a useful way of developing Web applications. I agree that the existing Net resources on REST leave out some details; had started doing some work on a RESTful product (in Python, later might port it to Java and Ruby) and think I should find the book useful to fill in those details and give me some guidance. For anyone else reading this comment, one of the co-authors of the RESTful book, Leonard Richardson, also co-wrote The Ruby Cookbook (published by O’Reilly), a very good book, IMO.
– Vasudev Ram
Dancing Bison Enterprises
http://www.dancingbison.com
Hey buddy! Nice blog that you maintain here.. I just chanced upon your blog surfing the blogosphere. I was thinking.. you could try out some interesting widgets on your page and spice it up with more relevant information. E.g try out the new widget on http://www.widgetmate.com with your relevant keywords