Today, InfoQ publishes a sample chapter from RESTful Web Services, a book authored by Leonard Richardson and Sam Ruby. The book covers the principles of the REST style, and explains how to build RESTful applications using Ruby on Rails, Restlet (for Java) and Django (for Python).
On this occasion, InfoQ's Stefan Tilkov had a chance to talk to the authors about their motivations for writing this book and their views on REST and Web services.
InfoQ: Leonard, how did you end up writing a book on REST?
Leonard Richardson (LR): I’ve been using the web as a programming environment since 1998. That is, I was screen-scraping. While I was messing around with that, people a few years older than me were formalizing the web as a programming environment. But the result looked very little like the web I love, and a whole lot like the distributed programming environments I was trying to avoid.
I was cheesed off about this for a number of years, and I recognized REST as the basis for a superior formalization, but I didn’t really do anything about it until I read an entry on Bill de hÓra’s weblog (he should really be in the Acknowledgements, actually).
Among other things he said “[W]e need a few good practical books on REST/HTTP to ship.” I’d just finished the Ruby Cookbook and I thought “Hey, I write books!” and that was the start.
InfoQ: Sam, you’ve been involved with the first phase of Web services, with SOAP builders, were an ApacheSOAP committer … was there something that changed your mind towards REST? Or was there never a real change of mind?
Sam Ruby (SR): Oh, there definitely was a mind change involved.
The thing that changed my mind was a code base called Blosxom initially by Rael Dornfest. Prior to exposure to that code, I had always operated under the assumption that the network was something that needed to be encapsulated and abstracted away. And here was a small piece of code with no dependencies which actually was simpler, more powerful, more maintainable, and more robust because it did NOT make these assumptions.
That, and the observation that the number of publicly available SOAP stacks continues to exceed the number of publicly deployed SOAP web services.
InfoQ: Can you give us the world’s shortest tutorial on what REST actually is? What’s the “elevator pitch”?
SR: Optimize the hell out of GET requests as that’s where most of your traffic will be.
LR: If I could add one sentence to Sam’s tutorial it would be “Give everything its own URI.”
As for an elevator pitch: there are hundreds of everyday activities that people used to do through the mail, over the phone, or through featureful Internet protocols like FTP and WAIS. Now we do these things over the web. The web’s interface (HTML, links, and forms) is very simple but it’s good enough to encapsulate all these disparate activities. Because everything works the same way it’s easy to use, and you get emergent properties like PageRank.
REST is a formal description of the vague things I just said: “simple” and “encapsulate” and “everything works the same way”. When you apply REST to the problem of distributed programming (as we do in the book), you get a simple architecture that can solve a huge number of problems in the space.
InfoQ: Since you mentioned GET’s importance: Is REST only a good fit for the mostly read-only Web, but not a good architecture for a high volume, mostly-write application?
LR: I think a RESTful architecture is the best one for any web service. (That is, if you don’t want REST you probably don’t want HTTP either.) But it’s much easier to make the case for read-only applications. A read-only RESTful web service works exactly the same way as a read-only web site. We’ve been exposing data through GET for 15 years. We know how to do it. We have client libraries in every language, debugging tools, transparent intermediaries like caching proxies.
But most websites don’t expose write operations RESTfully. They tend to put the operation name in the URI: /story/publish and /product/add-to-cart and so on. To get to REST you need to obey some kind of uniform interface constraint. This means thinking of the URI as identifying an object: /story and /product. A thing whose state you can change by sending messages.
This is not a huge conceptual leap, but it goes against today’s practice, so it’s not a no-brainer. We don’t have the tools or conventions we have for the read-only web. We’re still arguing about what the messages should look like and whether you should change state with POST+PUT+DELETE or if just POST is okay.
SR: I’ve done some work with databases. Even there, it has been my experience that it is a rare application that isn’t at least 90% read. Logging may be an exception, but placing a purchase order typically isn’t.
I’ll also readily concede that REST is not the solution to every problem, but I will note that if you find a problem where REST is not the solution, it does not immediately follow that WS-* is either.
InfoQ: One of the standard objections to REST is that it’s the architecture of a distributed hypermedia system — essentially, a system designed to deliver documents, possibly generated dynamically, to human end-users. What’s your explanation of why this works for machine-to-machine communication, too?
LR: A hypermedia system has two moving parts: objects and the links between them. If you model a data structure it has the same moving parts. Some pieces of data are information about the structure, and some are pointers to other structures. So hypermedia is a great way to let remote clients explore a data structure. And computers consume hypermedia documents the same way humans do. First you look at some of the data, then you see whether any of the links look interesting, then you follow the interesting ones.
An interesting case study is Amazon S3. It’s a RESTful service that exposes a very simple treelike structure: “buckets” that contain “objects”. When you GET a bucket you’re given an XML document that lists the names of all its objects. In a programming language this would be an array of references to the objects themselves. Here, it’s a list of hypermedia references you can use to GET the objects.
Now, it’s a very primitive form of hypermedia that I don’t recommend. The best way to link to an object is by its URI, and that list just has the names. To write an S3 client you must program in rules for translating an object name into a URI you can GET or PUT. But the names are hypermedia links in that their job is to serve as references to other objects.
SR: The net result is that an S3 client is only a client to S3 and S3 like systems. By contrast, web client is a client to the entire web.
One of the most successful new applications (and business model) that the web has enabled is search. If I take a look at the requests that my web site serves, I see that a lot of the requests are made by web crawlers. Web crawlers are applications. Applications that understand the hyperlinked nature of the web. Furthermore, most use the hyperlinks as metadata in order to rank search results.
In any case, most applications are state machines. With WS-*, state is pushed inside the envelope. With REST, state is pushed into the URI.
InfoQ: Another argument often brought up is that the standard claim that REST’s advantages have been proven by the Web’s success is actually a wrong conclusion — the reason being that most of the Web’s usage is actually non-RESTful.
LR: There’s some truth to this. Earlier I said that most websites don’t expose write operations RESTfully. But I think removing the non-RESTful parts of the Web would make the Web better, and wouldn’t hurt its success—except in the same second-order way it would hurt the Web’s success if web browsers were stricter about invalid HTML. I say this based on a short chapter I wrote for the REST book, exploring the reasons behind the Web’s success. I cut it because not many people are interested in detailed comparisons of the Web and Gopherspace—I think it’s just me and Rohit Khare. But basically I decided there were three important reasons: everything has an address, pages link to each other, and you can manipulate the web using only a web browser.
The first two correspond to important features of RESTful web services: addressability of resources by URI, and hypermedia-as-engine-of-application-state (which we call “connectedness” in the book). Rather than promoting REST by pointing to the Web as a whole, I would point to the incredible usefulness of URIs and links, two features largely ignored by WS-*.
InfoQ: It’s quite obvious that more and more people take REST seriously — a few years ago, they’re were only a few evangelists, and nowadays, everybody seems to seriously consider the REST alternative — even vendors such as Microsoft or Sun. Do you think REST is “winning”? Does this idea even make sense to you?
LR: The idea of “winning” certainly makes sense. There are still FTP sites and mail-order catalogs, but I hardly ever use them. The web has won, at least for me.
My random prediction is that WS-* architectures will not be used long- term for public-facing applications or other very-high-traffic applications. The big question in my mind is whether architectures consciously designed with REST in mind will “win” over architectures that are simple but only intermittently RESTful (not to pick on anybody, but check out the Flickr “REST” API).
SR: It certainly is becoming quite fashionable to layer a thin veneer of REST-like interfaces over top of an already many layered framework. A InfoQ:ick way to identify pretenders is to ask “do you support ETags?”. Any response, including a confident “no” which is not immediately followed by excuses or rationalizations, is to be treated as a correct answer.
LR: The “cargo cult REST” is quite understandable when there’s this huge gap between the formal definition of REST, which barely mentions HTTP, and the design of specific web services. A big goal of the book is to provide a baseline architecture for web services that’s seriously RESTful but also easy to put into practice.
InfoQ: What do you consider to be the benefits of REST over WS-*?
LR: The big one for me is the control it gives the users of the service. If your data is exposed through a large number of resources, I can get to the data I want very quickly, using a minimal software stack you may not explicitly support. When resources are identified by URI, I can feed the URIs into other services to make mashups. When resources link to each other, I can navigate them without internalizing a lot of complicated rules.
SR: This, in turn, is enabled by the consistency and constraints that REST mandates. In fact, it is not necessarily the case that any given SOAP service is complicated, but it is the case that pretty much every WSDL is custom made for that service, and therefore different. The net effect of having a different set of rules for each end point is a complex system.
InfoQ: Do you see a place for both REST and WS-*?
SR: There are a number of technologies, like ActiveX, which have taken root in a large number of intranets, but not on the internet. I see WS-* like that. If you have a small enough number of entities with enough mutual trust to consider deploying something like WS-Federation amongst yourselves, go for it.
LR: Basically what Sam said. In a homogeneous environment that’s under your control the network effects are different, and something like ActiveX or one of the more interesting WS-* standards might make sense.
There are also networks I know nothing about, like cell phone networks, where a RESTful architecture might not work. Just a guess.
InfoQ: What pieces available in the WS-* space are missing in the REST space?
SR: In theory, both describe roughly equivalent places where you can put headers for things like authentication and authorization. In practice, the WS-* folks have put more thought into security. Not that that gap couldn’t be closed if the will were there, but as a practical reality, that gap is a reality today.
LR: I’d like to see the gap closed. People who need one of the WS-Security tokens should be able to use it as an HTTP auth extension (a la WSSE) as well as a SOAP header. Other WS-* headers as they’re needed. Another missing piece is service description, which client-side programmers really like even though you can argue its theoretical basis in a RESTful system. I think WADL is going to do a great job here.
A related topic is tool support, and I’ve been a bit worried that when tools come, they’ll force peoples’ services into an RPC box and call them RESTful (see earlier cargo cult remark). But the tools so far — notably Restlet, Rails 1.2, and Thomas Steiner’s REST Describe — have been written with a good grasp of RESTful principles.
InfoQ: Do you want to give us a brief sales pitch for the book? What kind of reader did you have in mind when you wrote it?
LR: I was thinking of someone like I was when I started writing the book: a person who’s interested in REST but never quite sure if they’re applying the theory correctly.
SR: I also wanted a book that rose above the “we are 733T, WS are the Sux0rs” zealotry that, sadly, one too often hears. That’s not to say that the book isn’t opinionated — it most certainly is — but the emphasis is on practical applications, trade-offs, and yes, even dealing with the sometimes messy real world which doesn’t alway apply the theory consistently.
InfoQ: Thank you very much for your time.