RESTful Web Services Cookbook

Preface

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.

Scope of the Book

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.

Companion Material

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:

REST-Discuss Yahoo! Group (http://tech.groups.yahoo.com/group/rest-discuss)

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.

Leonard Richardson and Sam Ruby’s RESTful Web Services (O’Reilly)

See this book to learn more about REST and how to use the Web as a platform for building RESTful web services.

RESTwiki (http://rest.blueoxen.net/cgi-bin/wiki.pl)

This wiki contains a collection of articles written over years that describe various aspects of REST and its application.

Chris Shiflett’s HTTP Developer’s Handbook (Sams)

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.

How This Book Is Organized

This book is organized into 14 chapters followed by 5 appendixes as follows:

Chapter 1, Using the Uniform Interface

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, GET versus POST, etc. The recipes in this chapter primarily deal with using HTTP’s uniform interface.

Chapter 2, Identifying Resources

This chapter describes how to identify resources to cover some commonly encountered application scenarios.

Chapter 3, Designing Representations

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.

Chapter 4, Designing URIs

This chapter describes common patterns for designing URIs, using URIs as identifiers, and keeping URIs cool.

Chapter 5, Web Linking

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.

Chapter 6, Atom and AtomPub

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.

Chapter 7, Content Negotiation

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.

Chapter 8, Queries

This chapter shows some approaches for designing URIs for queries, handling large queries, and storing queries.

Chapter 9, Web Caching

This chapter describes how to support expiration caching in servers and deal with caching in clients.

Chapter 10, Conditional Requests

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.

Chapter 11, Miscellaneous Writes

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.

Chapter 12, Security

This chapter shows how to address common security needs such as authentication, authorization, delegation, etc.

Chapter 13, Extensibility and Versioning

This chapter shows how to write extensible servers, how to keep clients resilient to change, and how to implement versioning.

Chapter 14, Enabling Discovery

This chapter describes how to document RESTful web services.

Appendix A

This appendix lists places where you can find more information about REST and the underlying technologies.

Appendix B

This appendix provides a brief introduction to REST with an example.

Appendix C

This appendix shows how to use standard HTTP methods.

Appendix D

This appendix provides a reference to Atom feed and entry documents.

Appendix E

This appendix lists link relation types that you can use in links.

Conventions Used in This Book

The following typographical conventions are used in this book:

Italic

Indicates new terms, URLs, email addresses, filenames, and file extensions.

Constant width

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>

Tip

This icon signifies a tip, suggestion, or general note.

Caution

This icon indicates a warning or caution.

Using Code Examples

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 [e-mail].

Safari® Books Online

Note

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.

How to Contact Us

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)

707-829-0104 (fax)

We have a web page for this book, where we list errata, examples, and any additional information. You can access this page at:

http://www.oreilly.com/catalog/9780596801687

To comment or ask technical questions about this book, send email to:

[e-mail]

For more information about our books, conferences, Resource Centers, and the O’Reilly Network, see our website at:

http://www.oreilly.com

Acknowledgments

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.

Thanks also to all the readers who provided feedback on the rough cuts drafts of this book.

Mike Amundsen’s Contribution

Mike Amundsen contributed to Recipes 4.1, 4.3, 6.1, 6.4, 9.1, 9.4, 9.5, 11.8, 11.9, 11.12, and Appendix D.