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 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. Wikipedias entry on Representational State Transfer (http://en.wikipedia.org/wiki/Representational_State_Transfer) provides a concise description of RESTs underlying concepts, its constraints, and the guiding principles to design applications. Leonard Richardson and Sam Rubys RESTful Web Services (OReilly) 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 for a list of programming languagespecific 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 OReilly), 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 Rubys RESTful Web Services (OReilly)
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 Shifletts HTTP Developers 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:
This chapter describes the details of using HTTPs 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 HTTPs uniform interface.
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.