a book by Leonard Richardson and Sam Ruby
Deprecation notice: RESTful Web Services has been replaced by a new book, 2013's RESTful Web APIs. You can download the original RESTful Web Services in PDF, EPUB, MOBI or DAISY format. You can also read an HTML version online.
The work RESTful Web Services is now licensed under a Creative Commons Attribution-NonCommercial-NoDerivs 3.0 Unported License.
Every IT generation has its seminal tome that transcends time and connects the dots in a way that no book had before it. For the object oriented generation in the 1980s, it was the Gang of Four (GoF) book. For the application architecture generation in the 1990s, it was Fowler's book on patterns (PoEAA). "RESTful Web Services" will be, in my opinion, that book for the 2000s Web services generation.
[B]ound to become a classic: well written, well structured, very informative and fairly independent of the daily trends.
The new great subversive computer book is here.
Every developer working with the Web needs to read this book.--David Heinemeier Hansson
To design a website you need to know about HTTP, XHTML, and URIs.
To design a web application you need to know about HTTP, XHTML, and URIs.
To design a web service you need to know about XML, SOAP, WSDL, UDDI, WS-Policy, WS-Security, WS-Eventing, WS-Reliability, WS-Coordination, WS-Transaction, WS-Notification, WS-BaseNotification, WS-Topics, WS-Transfer...
What happened there? The web is the most successful distributed platform in the world, and it's simple enough for average humans to understand. How come adapting it for use by computer programs requires that smart people spend billions of dollars and devote years of their lives to coming up with all these new standards? And what happened to HTTP and URIs?
The answer is that "Web Services" aren't the web. They're a heavyweight architecture for distributed object access, like COM and CORBA. This architecture is associated with the web, because HTTP is a trendy protocol, and flexible enough that you can implement almost anything on top of it. But it's not really of the web. The architecture of Big Web Services reinvents or ignores every feature that makes the web successful.
This is the book that puts the "web" back into "web services". You can design a web service that uses HTTP, XHTML, and URIs. You just need to understand REST, the architectural principles that drive the web. RESTful Web Services gives you the tools you need to argue for sensible web services, and the strategies and code you need to create them.
RESTful Web Services was published by O'Reilly in May 2007. We think this is the definitive work on the real-world use of REST.
We want to restore the World Wide Web to its rightful place as a respected architecture for distributed programming. We want to shift the focus of web service programming from an RPC-style architecture that just happens to use HTTP as a transfer protocol, to a URI-based architecture that uses the technologies of the web to their fullest.
Our project has technical aspects but it's mainly a job of evangelizing: spreading the good news. Currently the REST philosophy is typecast as sloppy or unserious. This despite the fact that:
If REST doesn't work or doesn't "scale", then neither does the World Wide Web.
REST is typecast because its practices are folklore. It's got no canonical documentation beyond a doctoral thesis which, like most holy texts, says little about how to apply its teachings to everyday life. Its technologies are so old and heavily-used they seem undocumented and unsupported when their true power is revealed. It's like finding out you can pick a lock with a paperclip.
Because it occupies this odd middle ground—familiar yet suddenly cast in a new light—a lot of people have gotten the impression that REST just means "whatever you want to do, so long as you don't use SOAP". That it's a sloppy no-methodology used to justify bad design, malformed XML, and, in particularly troublesome cases, Extreme Programming. We're writing a book to codify the folklore, define what's been left undefined, and try to move past the theological arguments.
In general we espouse a big-tent approach to REST. We're not going to kick people out for using overloaded POST when they should use DELETE (though we think anyone who does that should know what they're doing). We have our own ideas about URI and representation design, but we consider them nothing more than guidelines; we're not willing to fight over them.
We are willing to fight over HTTP's concept of resources. We think resources are what separate real REST services from the REST-RPC hybrids, the HTTP+POX hoi polloi. We love resources. "If you love resources so much," some have said, "why don't you marry them?" Well, both of us are happily married already, but thanks for thinking of us. But you know how some people name boats or puppies after the things they love? We named our architecture after resources. It's called the Resource-Oriented Architecture.
The ROA is the name we give to REST when combined with our codified version of folklore. We came up with a new term because REST isn't an architecture: it's an architectural style, a way of judging architectures. It's not even tied to HTTP. Which is fine, but it means that there's a largely undefined path from RESTful principles, to principles of HTTP-based applications, to principles of web services in particular, to the design of specific services. The ROA is a way-station along that path: an alternate starting point that gets you more quickly to the design of specific services. The ROA is a concrete architecture specifically designed for web services, with a procedure you can follow to turn requirements into resources.
The introduction sets up the argument of this book: that there's no real difference between the Internet-scale distributed platform people use themselves (the World Wide Web) and the Internet-scale distributed platform people write programs to use (the programmable web, a.k.a. "web services"). That the World Wide Web is a good enough application platform for most web services; good enough, in fact, to be considered the default solution. That additional layers on the stack don't pay for themselves: they give you features you almost never need, they reinvent features of HTTP and TCP/IP, and they destroy or marginalize most of what's good about the web: specifically, URIs and links.
This chapter introduces web services in general: programs that go over the Web to ask a foreign server to provide data or run an algorithm. It presents two questions you can ask about a service's design to classify it as RESTful or as RPC-style. Throughout the chapter are sample HTTP requests and responses, letting you see the different architectures in action. We also include sample Ruby clients that run against popular web services of all types.
Most services commonly considered "RESTful" do overlap with REST, but also have elements of the RPC style (for instance, the Flickr and del.icio.us APIs). This chapter shows why this happens and why many people think these services are RESTful.
This chapter shows how to write clients for URI-based services (RESTful services and REST-RPC hybrids) in various programming languages. It goes into more detail than the overview in chapter 1. But it presumes no knowledge of any particular architecture. The ROA we provide in the next section is our prescriptive vision and most existing services fall short of it in some way.
We give a brief client-oriented introduction to HTTP, and to the DOM, SAX, and pull strategies for parsing XML (the document format most commonly served by web services). We give library recommendationas for today's most common programming languages.
Our example service is the del.icio.us web API, a REST-RPC hybrid service. We give sample applications in Ruby, Python, Java, C#, and PHP. (A Javascript client is shown in the Ajax chapter.)
The del.icio.us web API serves XML documents. We briefly cover JSON, an alternate way of representing data commonly found in Ajax applications and Yahoo!'s web services.
We give a brief introduction to the Web Application Description Language, again using the del.icio.us API as an example. If a service provides a WADL file, and your language has a WADL library, then using a RESTful or hybrid service is as easy as using a SOAP service with WSDL. This is just a taste of the WADL coverage in the "Building Blocks" chapter.
This chapter continues where the previous one left off, with a focus on what RESTful web services do differently. The primary example is Amazon's Simple Storage Service (S3). We write an S3 client in Ruby as a way of introducing concepts like resources, representations, and the uniform interface. Our client is for educational purposes only; there are better libraries if you actually want to use S3 in your programs.
We create a simple RESTful service using Rails 1.2's
scaffold_resource generator, just so we can introduce the
ActiveResource client library. We present a short ActiveResource
script that manipulates the generated service, and an equivalent
script written in Python that uses ElementTree and httplib2.
This chapter introduces the concepts of REST within a specific RESTful architecture we call the Resource-Oriented Architecture. This chapter defines much REST terminology first covered in chapter 3: resources, their URIs, their representations, and the links between them. It covers the main goals of REST: addressibility, statelessness, connectedness, and the uniform interface.
This chapter shows how to design simple, RESTful web services that don't do anything but serve data. The main topics we cover are: choosing your resources, giving them useful URIs and representations, and fastening everything together into a request/response cycle. Other topics include using hypermedia (links and forms) to drive application state.
The main example throughout the chapter is a service that serves navigable maps and named places on the maps. It's inspired by the URI-oriented interface to the image tiles served by Google Maps, but we take the concept of a map server and take it all the way into the world of REST.
This chapter expands on the previous one to show how to design services where clients can modify the dataset. The main topics are user authentication, and the addition of POST/PUT/DELETE requests to the previous chapter's GET and HEAD.
The example continues the example from the previous chapter, enhancing the map service so that clients can annotate the maps with places that they define. There's also some more juicy resource design: we treat user accounts as resources that can be created and destroyed programatically.
We design a web service for social bookmarking, and then implement it as a Rails application. This service is based on the del.icio.us API and website. It builds on the introduction of the del.icio.us API in "Writing Web Service Clients" to show what del.icio.us would look like as a resource-oriented service. Because our service is based on an existing, non-RESTful service, this chapter doubles as a case study for converting from an RPC interface to a resource-oriented interface.
This chapter collects in one place the best practices from elsewhere in the book, and adds others. It includes brief essays arguing for the four main points of the ROA. The chapter also covers URI opacity versus readable URIs, encoding issues, and standard features of HTTP such as authentication and conditional GET. It shows resource-oriented designs for things you may have thought HTTP couldn't do: transactions, asynchronous operations, and batch operations.
This chapter covers preexisting standards that can help you build a web service, and makes recommendations. We talk about many representation formats, with a focus on XHTML microformats and extensible XML. We covers hypermedia standards (URI Templating, XHTML, and WADL), and prepackaged control flows like the Atom Publishing Protocol, GData, and Post Once Exactly.
The main event. We single-handledly take on an enormous, multi-billion-dollar project that has alrady had about 25 books written about it. We explain the main technologies and concepts of the SOAP/WSDL/WS-* conglomorate. We show which parts can coexist with a RESTful style, which parts conflict, and which parts just add needless complexity. We give suggestions for making SOAP-based services more RESTful. We discuss resource-oriented alternatives to the BWS technologies and, we bring up the possibility of porting WS-* ideas to HTTP headers (as happened with WSSE).
This chapter introduces the Ajax architecture as a way of writing REST clients that run in a web browser, rather than standalone. In terms of code the focus is almost entirely on Ajax applications written in Javascript.
This chapter is mainly written for people who know about Ajax
but hadn't thought about it in terms of web services. It does cover
Javascript's XmlHttpRequest in a fair amount of detail,
as an extension of the "Writing Clients..." chapter.
The chapter closes by showing various ways of making cross-domain web service calls: the obvious next step once you start thinking about Ajax applications as web service clients. Most of these ways are pretty sneaky.
This chapter covers server-side frameworks for building RESTful web services. We cover Rails, Restlet, and Django. We show how the frameworks work in the abstract, and for Restlet and Django we show snippets from implementations of social bookmarking services, like the Rails one in chapter 7.
This appendix lists sources on the web that talk more about REST and the standards we cover in the book. It also links to a number of public, RESTful, resource-oriented web services whose design you can study.
One of the distinguishing features of REST is its use of HTTP status codes to convey information about the nature of the representation. There are over 40 HTTP status codes, an overwhelming number. Which ones do you really need? When would you use each one? This appendix is a guide.
Similar to appendix B, but for HTTP headers. Includes some
important headers not mentioned in the HTTP standard, like
X-WSSE and the APP's Slug.
|
This document is part of Crummy, the webspace of Leonard Richardson (contact information). It was last modified on Friday, October 04 2013, 14:53:14 Nowhere Standard Time and last built on Thursday, April 25 2024, 08:00:11 Nowhere Standard Time.
| Document tree: Site Search: |
