Transcription of RESTful Web Services
1 RESTful Web ServicesRESTful Web ServicesLeonard Richardson and Sam RubyBeijing Cambridge Farnham K ln Sebastopol TokyoRESTful Web Servicesby Leonard Richardson and Sam RubyCopyright 2007 O Reilly Media. All rights in the United States of by O Reilly Media, Inc., 1005 Gravenstein Highway North, Sebastopol, CA 95472O Reilly books may be purchased for educational, business, or sales promotional use. Online editionsare also available for most titles ( ). For more information, contact our corporate/institutional sales department: (800) 998-9938 or LoukidesCopy Editor:Peggy WallaceProduction Editor:Laurel RumaProofreader:Laurel RumaIndexer:Joe WizdaCover Designer:Karen MontgomeryInterior Designer:David FutatoIllustrators:Robert Romano and Jessamyn ReadPrinting History:May 2007:First EditionNutshell Handbook, the Nutshell Handbook logo, and the O Reilly logo are registered trademarks ofO Reilly Media, Inc.
2 The vulpine phalanger and related trade dress are trademarks of O Reilly Media, of the designations uses by manufacturers and sellers to distinguish their products are claimed astrademarks. Where those designations appear in this book, and O Reilly Media, Inc. was aware of atrademark claim, the designations have been printed in caps or initial every precaution has been taken in the preparation of this book, the publisher and authors assumeno responsibility for errors or omissions, or for damages resulting from the use of the information con-tained : 978-0-596-52926-0[LSI][2011-04-15]130288 4426 For Woot, Moby, and Beet.
3 LeonardFor Christopher, Catherine, and Carolyn. SamTable of ContentsForeword .. xiPreface .. xiii1. The Programmable Web and Its Inhabitants .. 1 Kinds of Things on the Programmable Web4 HTTP: Documents in Envelopes5 Method Information8 Scoping Information11 The Competing Architectures13 Technologies on the Programmable Web18 Leftover Terminology202. Writing Web Service Clients .. 23 Web Services Are Web : The Sample Application26 Making the Request: HTTP Libraries29 Processing the Response: XML Parsers38 JSON Parsers: Handling Serialized Data44 Clients Made Easy with WADL473. What Makes RESTful Services Different?
4 49 Introducing the Simple Storage Service49 Object-Oriented Design of S350 Resources52 HTTP Response Codes54An S3 Client55 Request Signing and Access Control64 Using the S3 Client Library70 Clients Made Transparent with ActiveResource71 Parting Words77vii4. The Resource-Oriented Architecture .. 79 Resource-Oriented What Now?79 What s a Resource?81 URIs81 Addressability84 Statelessness86 Representations91 Links and Connectedness94 The Uniform Interface96 That s It!1055. Designing Read-Only Resource-Oriented Services .. 107 Resource Design108 Turning Requirements Into Read-Only Resources109 Figure Out the Data Set110 Split the Data Set into Resources112 Name the Resources117 Design Your Representations123 Link the Resources to Each Other135 The HTTP Response137 Conclusion1406.
5 Designing Read/Write Resource-Oriented Services .. 143 User Accounts as Resources144 Custom Places157A Look Back at the Map Service1657. A Service Implementation .. 167A Social Bookmarking Web Service167 Figuring Out the Data Set168 Resource Design171 Design the Representation(s) Accepted from the Client183 Design the Representation(s) Served to the Client184 Connect Resources to Each Other185 What s Supposed to Happen?186 What Might Go Wrong?187 Controller Code188 Model Code205 What Does the Client Need to Know?2098. REST and ROA Best Practices .. 215 Resource-Oriented Basics215viii|Table of ContentsThe Generic ROA Procedure216 Addressability216 State and Statelessness217 Connectedness218 The Uniform Interface218 This Stuff Matters221 Resource Design227 URI Design233 Outgoing Representations234 Incoming Representations234 Service Versioning235 Permanent URIs Versus Readable URIs236 Standard Features of HTTP237 Faking PUT and DELETE251 The Trouble with Cookies252 Why Should a User Trust the HTTP Client?
6 2539. The Building Blocks of Services .. 259 Representation Formats259 Prepackaged Control Flows272 Hypermedia Technologies28410. The Resource-Oriented Architecture Versus Big Web Services .. 299 What Problems Are Big Web Services Trying to Solve?300 SOAP300 WSDL304 UDDI309 Security310 Reliable Messaging311 Transactions312 BPEL, ESB, and SOA313 Conclusion31411. Ajax Applications as REST Clients .. 315 From AJAX to Ajax315 The Ajax Architecture316A Example317 The Advantages of Ajax320 The Disadvantages of Ajax321 REST Goes Better322 Making the Request323 Handling the Response324 JSON325 Table of Contents|ixDon t Bogart the Benefits of REST326 Cross-Browser Issues and Ajax Libraries327 Subverting the Browser Security Model33112.
7 Frameworks for RESTful Services .. 339 Ruby on Rails339 Restlet343 Django355A. Some Resources for REST and Some RESTful Resources .. 365B. The HTTP Response Code Top 42 .. 371C. The HTTP Header Top Infinity .. 389 Index .. 409x|Table of ContentsForewordThe world of web Services has been on a fast track to supernova ever since the architectastronauts spotted another meme to rocket out of pragmatism and into the universe ofenterprises. But, thankfully, all is not lost. A renaissance of HTTP appreciation isbuilding and, under the banner of REST, shows a credible alternative to what the mer-chants of complexity are trying to ram down everyone s throats; a simple set of prin-ciples that every day developers can use to connect applications in a style native to Web Services shows you how to use those principles without the drama, thebig words, and the miles of indirection that have scared a generation of web developersinto thinking that web Services are so hard that you have to rely on BigCo implemen-tations to get anything done.
8 Every developer working with the Web needs to read thisbook. David Heinemeier HanssonxiPrefaceA complex system that works is invariably found to haveevolved from a simple system that worked. John GallSystemanticsWe wrote this book to tell you about an amazing new technology. It s here, it s hot,and it promises to radically change the way we write distributed systems. We re talkingabout the World Wide , it s not a new technology. It s not as hot as it used to be, and from a technicalstandpoint it s not incredibly amazing. But everything else is true. In 10 years the Webhas changed the way we live, but it s got more change left to give.
9 The Web is a simple,ubiquitous, yet overlooked platform for distributed programming. The goal of thisbook is to pull out that change and send it off into the may seem strange to claim that the Web s potential for distributed programming hasbeen overlooked. After all, this book competes for shelf space with any number of otherbooks about web Services . The problem is, most of today s web Services have nothingto do with the Web. In opposition to the Web s simplicity, they espouse a heavyweightarchitecture for distributed object access, similar to COM or CORBA. Today s webservice architectures reinvent or ignore every feature that makes the Web doesn t have to be that way.
10 We know the technologies behind the Web can driveuseful remote Services , because those Services exist and we use them every day. Weknow such Services can scale to enormous size, because they already do. Consider theGoogle search engine. What is it but a remote service for querying a massive databaseand getting back a formatted response? We don t normally think of web sites as serv-ices, because that s programming talk and a web site s ultimate client is a human, butservices are what they web application every web site is a service. You can harness this power forprogrammable applications if you work with the Web instead of against it, if you don tbury its unique power under layers of abstraction.
