Ruby Sam Richardson Leonard - RESTful web services: Includes index

Copyright 2008 Leonard Richardson and Sam Ruby

OReilly books may be purchased for educational, business, or sales promotional use. Online editions are also available for most titles (.

Nutshell Handbook, the Nutshell Handbook logo, and the OReilly logo are registered trademarks of OReilly Media, Inc. The vulpine phalanger and related trade dress are trademarks of OReilly Media, Inc.

Many of the designations uses by manufacturers and sellers to distinguish their products are claimed as trademarks. Where those designations appear in this book, and OReilly Media, Inc. was aware of a trademark claim, the designations have been printed in caps or initial caps.

While every precaution has been taken in the preparation of this book, the publisher and authors assume no responsibility for errors or omissions, or for damages resulting from the use of the information contained herein.

This book uses RepKover, a durable and flexible lay-flat binding.

The world of web services has been on a fast track to supernova ever since the architect astronauts spotted another meme to rocket out of pragmatism and into the universe of enterprises. But, thankfully, all is not lost. A renaissance of HTTP appreciation is building and, under the banner of REST, shows a credible alternative to what the merchants of complexity are trying to ram down everyones throats; a simple set of principles that every day developers can use to connect applications in a style native to the Web.

RESTful Web Services shows you how to use those principles without the drama, the big words, and the miles of indirection that have scared a generation of web developers into thinking that web services are so hard that you have to rely on BigCo implementations to get anything done. Every developer working with the Web needs to read this book.

We wrote this book to tell you about an amazing new technology. Its here, its hot, and it promises to radically change the way we write distributed systems. Were talking about the World Wide Web.

Okay, its not a new technology. Its not as hot as it used to be, and from a technical standpoint its not incredibly amazing. But everything else is true. In 10 years the Web has changed the way we live, but its got more change left to give. The Web is a simple, ubiquitous, yet overlooked platform for distributed programming. The goal of this book is to pull out that change and send it off into the world.

It may seem strange to claim that the Webs potential for distributed programming has been overlooked. After all, this book competes for shelf space with any number of other books about web services. The problem is, most of todays web services have nothing to do with the Web. In opposition to the Webs simplicity, they espouse a heavyweight architecture for distributed object access, similar to COM or CORBA. Todays web service architectures reinvent or ignore every feature that makes the Web successful.

It doesnt have to be that way. We know the technologies behind the Web can drive useful remote services, because those services exist and we use them every day. We know such services can scale to enormous size, because they already do. Consider the Google search engine. What is it but a remote service for querying a massive database and getting back a formatted response? We dont normally think of web sites as services, because thats programming talk and a web sites ultimate client is a human, but services are what they are.

Every web applicationevery web siteis a service. You can harness this power for programmable applications if you work with the Web instead of against it, if you dont bury its unique power under layers of abstraction. Its time to put the web back into web services.

The features that make a web site easy for a web surfer to use also make a web service API easy for a programmer to use. To find the principles underlying the design of these services, we can just translate the principles for human-readable web sites into terms that make sense when the surfers are computer programs.

Thats what we do in this book. Our goal throughout is to show the power (and, where appropriate, the limitations) of the basic web technologies: the HTTP application protocol, the URI naming standard, and the XML markup language. Our topic is the set of principles underlying the Web: Representational State Transfer, or REST. For the first time, we set down best practices for RESTful web services. We cut through the confusion and guesswork, replacing folklore and implicit knowledge with concrete advice.

We introduce the Resource-Oriented Architecture (ROA), a commonsense set of rules for designing RESTful web services. We also show you the view from the client side: how you can write programs to consume RESTful services. Our examples include real-world RESTful services like Amazons Simple Storage Service (S3), the various incarnations of the Atom Publishing Protocol, and Google Maps. We also take popular services that fall short of RESTfulness, like the del.icio.us social bookmarking API, and rehabilitate them.