In 2000, Roy Fielding, one of the key contributors to HTTP and URI, codified the architecture of the Web in his doctoral thesis titled “Architectural Styles and the Design of Network-Based Software Architectures.” In this thesis, he introduced an architecture style known as Representational State Transfer (REST). This style, in abstract terms, describes the foundation of the World Wide Web. The technologies that make up this foundation include the Hypertext Transfer Protocol (HTTP), Uniform Resource Identifier (URI), markup languages such as HTML and XML, and web-friendly formats such as JSON.
REST is an architectural style for networked applications. It consists of several constraints to address separation of concerns, visibility, reliability, scalability, performance, etc. See Appendix B for a brief overview of these constraints. What makes REST attractive to build distributed and decentralized client/server applications is the infrastructure of the Web. Deploying web services on this infrastructure lets you take advantage of a wide range of existing infrastructure that includes web servers, client libraries, proxy servers, caches, firewalls, and so on. Although, in theory, it is possible to build RESTful applications without relying on HTTP, attempting to do so can be an expensive proposition. In this book, RESTful web services means web services built using HTTP, URIs, XML, JSON, Atom, etc.
This book is not a discourse on REST or its merits over other styles of architecture. This is a cookbook for designers and developers of RESTful web services.
Plenty of material exists that describes the REST architectural style. Wikipedia’s entry on Representational State Transfer (http://en.wikipedia.org/wiki/Representational_State_Transfer) provides a concise description of REST’s underlying concepts, its constraints, and the guiding principles to design applications. Leonard Richardson and Sam Ruby’s RESTful Web Services (O’Reilly) provides a more in-depth coverage on the basics of this topic detailing how to use resources as the core building blocks. But how do you find help with day-to-day design and implementation questions? This is the book to fill that gap.
This book consists of recipes to help design and implement RESTful client/server applications. It presents these recipes in a manner that lets you take advantage of the web infrastructure and REST without having to ponder whether your web service is RESTful. Each recipe includes one or more problem statements and a solution, followed by a detailed discussion with examples, commentary on implementation, and any trade-offs involved.
Much of the material for the recipes is based on common design problems found while developing RESTful web services. The problems include usage of HTTP, resource and representation design, URIs, caching, concurrency control, partial updates, batch processing, transactions, security, versioning, compatibility, etc.
This book is not programming language specific. It uses HTTP request and response messages to illustrate implementation. You can use languages such as C#, C++, Java, Ruby, Python, PHP, and Perl to implement these recipes. See Appendix A for a list of programming language–specific books, or search your favorite bookstore.
This book does not also deal with installing, administering, or securing web servers, caches, and proxies. See books such as Apache Cookbook by Ken Coar and Rich Bowen, Apache Security by Ivan Ristic, and Squid: The Definitive Guide by Duane Wessels (all from O’Reilly), or product manuals to learn such topics.
See http://www.restful-webservices-cookbook.org for additional material, errata, comments, and questions about this book.
You may find the following additional resources helpful:
If you have questions on the REST architectural style, search the archives of this group. Better yet, join this group to post your questions and engage in conversations about the merits and demerits of REST, commonly encountered problems, and usage of HTTP for RESTful web services.
See this book to learn more about REST and how to use the Web as a platform for building RESTful web services.
This wiki contains a collection of articles written over years that describe various aspects of REST and its application.
See this book if you have questions about using HTTP in client or server applications.
Undoubtedly, there will be additional design and implementation problems that are not addressed by this book or the previously discussed resources. Visit http://www.restful-webservices-cookbook.org to post your questions, suggestions, or alternative solutions you have had success with in your experience. In due course, this site will include additional recipes, and they will be included in the next revision of this book.
This book is organized into 14 chapters followed by 5 appendixes as follows:
This chapter describes the details of using HTTP’s uniform
interface and deals with issues such as statelessness, visibility,
safety and idempotency, extensibility, new resource creation,
POST, etc. The recipes in
this chapter primarily deal with using HTTP’s uniform
This chapter describes how to identify resources to cover some commonly encountered application scenarios.
This chapter describes how to design representations, how to use HTTP headers on requests and responses, how to choose media types and formats, and how to do error handling.
This chapter describes common patterns for designing URIs, using URIs as identifiers, and keeping URIs cool.
This chapter shows when and how to use links in representations and covers details of links in the body of representations, link headers, URI templates, and applications of links.
This chapter presents how to use Atom feeds, entries, media resources, and service documents as resources; how to use the AtomPub protocol; and when to use Atom to design resource representations.
This chapter shows how to negotiate for representations
based on media type, character encoding, content encoding, or
content language; how to use the
Vary header; and
when to use content negotiation.
This chapter shows some approaches for designing URIs for queries, handling large queries, and storing queries.
This chapter describes how to support expiration caching in servers and deal with caching in clients.
This chapter describes how to implement conditional requests in servers and clients for various HTTP methods and shows how conditional requests can help caching, optimistic concurrency control, and idempotency.
This chapter shows how to solve a variety of design problems that at first glance may seem outside the scope of REST and HTTP. Topics include copying, merging, partial updates, batch processing, and transactions.
This chapter shows how to address common security needs such as authentication, authorization, delegation, etc.
This chapter shows how to write extensible servers, how to keep clients resilient to change, and how to implement versioning.
This chapter describes how to document RESTful web services.
This appendix lists places where you can find more information about REST and the underlying technologies.
This appendix provides a brief introduction to REST with an example.
This appendix shows how to use standard HTTP methods.
This appendix provides a reference to Atom feed and entry documents.
This appendix lists link relation types that you can use in links.
The following typographical conventions are used in this book:
Indicates new terms, URLs, email addresses, filenames, and file extensions.
Used for program listings, as well as within paragraphs to refer to program elements such as variable or function names, databases, datatypes, environment variables, statements, and keywords.
Constant width starting with "#"
Used for comments in HTTP requests and response messages. For instance:
# This is a request GET /toc Host: www.restful-webservices-cookbook.org # This is a response HTTP/1.1 200 OK Date: Sat, 07 Nov 2009 03:14:05 GMT Last-Modified: Sat, 07 Nov 2009 03:14:05 GMT Content-Type: text/html; charset=UTF-8 <html>...</html>
This icon signifies a tip, suggestion, or general note.
This icon indicates a warning or caution.
This book is here to help you get your job done. In general, you may use the code in this book in your programs and documentation. You do not need to contact us for permission unless you’re reproducing a significant portion of the code. For example, writing a program that uses several chunks of code from this book does not require permission. Selling or distributing a CD-ROM of examples from O’Reilly books does require permission. Answering a question by citing this book and quoting example code does not require permission. Incorporating a significant amount of example code from this book into your product’s documentation does require permission.
We appreciate, but do not require, attribution. An attribution usually includes the title, author, publisher, and ISBN. For example: “RESTful Web Services Cookbook by Subbu Allamaraju. Copyright 2010 Yahoo!, Inc., 978-0-596-80168-7.”
If you feel your use of code examples falls outside fair use or the permission given here, feel free to contact us at firstname.lastname@example.org.
Safari Books Online is an on-demand digital library that lets you easily search over 7,500 technology and creative reference books and videos to find the answers you need quickly.
With a subscription, you can read any page and watch any video from our library online. Read books on your cell phone and mobile devices. Access new titles before they are available for print, and get exclusive access to manuscripts in development and post feedback for the authors. Copy and paste code samples, organize your favorites, download chapters, bookmark key sections, create notes, print out pages, and benefit from tons of other time-saving features.
O’Reilly Media has uploaded this book to the Safari Books Online service. To have full digital access to this book and others on similar topics from O’Reilly and other publishers, sign up for free at http://my.safaribooksonline.com.
Please address comments and questions concerning this book to the publisher:
|O’Reilly Media, Inc.|
|1005 Gravenstein Highway North|
|Sebastopol, CA 95472|
|800-998-9938 (in the United States or Canada)|
|707-829-0515 (international or local)|
We have a web page for this book, where we list errata, examples, and any additional information. You can access this page at:
To comment or ask technical questions about this book, send email to:
For more information about our books, conferences, Resource Centers, and the O’Reilly Network, see our website at:
Many people have helped this book happen. Mary Treseler, the editor for this book at O’Reilly, helped shape the outline for this book by asking the right questions. She provided much needed support, encouragement, and polite nudging to transform ideas into a reality.
Many thanks to Mark Nottingham and Hugo Haas for helping me draft an initial outline for this book.
Mike Amundsen, who contributed to parts of this book, spent countless hours and red pens to review and comment on the book line by line. His suggestions on improving the tone of this book were invaluable. Despite his limited availability, Mike was always on call to discuss the merits and demerits of solutions and the real-world trade-offs.
Thanks to Havi Hoffman, who manages Yahoo! Press, for patiently guiding me through the process of writing a proposal and for pulling the right strings to shield me from the elaborate process. My thanks to Neal Sample, James Lok, Jay Rossiter, and Tony Ng (all from Yahoo! Inc.) for their support during the course of writing this book. I would also like to thank Korby Parnell for planting the seeds to write this book.
I am profoundly grateful to Mark Nottingham, Eben Hewitt, Colin Jack, Stefan Tilkov, Norbert Lindenberg, Chris Westin, Dan Theurer, Shaunak Kashyap, Larry Cable, Alan Dean, Surya Suravarapu, Jim D’Ambrosia, Randolph Kahle, Dhananjay Nene, and Brian Sletten for their valuable and critical feedback on the clarity, approach, quality, and accuracy of the material in this book.
Thanks to the members of the REST-Discuss Yahoo! Group (http://tech.groups.yahoo.com/group/rest-discuss) for all the passionate, tough, and insightful discussions on all things related to REST.