book

RESTful Web Services

Name: RESTful Web Services
ISBN: 9780596529260

by Leonard Richardson, Sam Ruby

May 2007

Intermediate to advanced

446 pages

14h 31m

English

O'Reilly Media, Inc.

Read now

Unlock full access

Dedication
A Note Regarding Supplemental Files
Foreword
Preface
The Web Is SimpleBig Web Services Are Not SimpleThe Story of the RESTReuniting the WebsWhat’s in This Book?Administrative NotesConventions Used in This BookUsing Code ExamplesSafari® EnabledHow to Contact UsAcknowledgments
1. The Programmable Web and Its Inhabitants
Kinds of Things on the Programmable WebHTTP: Documents in EnvelopesMethod InformationScoping InformationThe Competing ArchitecturesRESTful, Resource-Oriented ArchitecturesRPC-Style ArchitecturesREST-RPC Hybrid ArchitecturesThe Human Web Is on the Programmable WebTechnologies on the Programmable WebHTTPURIXML-RPCSOAPWS-*WSDLWADLLeftover Terminology
2. Writing Web Service Clients
Web Services Are Web SitesWrappers, WADL, and ActiveResourcedel.icio.us: The Sample ApplicationWhat the Sample Clients DoMaking the Request: HTTP LibrariesOptional FeaturesRuby: rest-open-uri and net/httpPython: httplib2Java: HttpClientC#: System.Web.HTTPWebRequestPHP: libcurlJavaScript: XMLHttpRequestThe Command Line: curlOther LanguagesProcessing the Response: XML ParsersRuby: REXML, I GuessPython: ElementTreeJava: javax.xml, Xerces, or XMLPullC#: System.Xml.XmlReaderPHPJavaScript: responseXMLOther LanguagesJSON Parsers: Handling Serialized DataClients Made Easy with WADL
3. What Makes RESTful Services Different?
Introducing the Simple Storage ServiceObject-Oriented Design of S3A Few Words About BucketsA Few Words About ObjectsWhat If S3 Was a Standalone Library?ResourcesHTTP Response CodesAn S3 ClientThe Bucket ListThe BucketThe S3 ObjectRequest Signing and Access ControlSigning a URISetting Access PolicyUsing the S3 Client LibraryClients Made Transparent with ActiveResourceCreating a Simple ServiceAn ActiveResource ClientA Python Client for the Simple ServiceParting Words
4. The Resource-Oriented Architecture
Resource-Oriented What Now?What’s a Resource?URIsURIs Should Be DescriptiveThe Relationship Between URIs and ResourcesAddressabilityStatelessnessApplication State Versus Resource StateRepresentationsDeciding Between RepresentationsLinks and ConnectednessThe Uniform InterfaceGET, PUT, and DELETEHEAD and OPTIONSPOSTCreating subordinate resourcesAppending to the resource stateOverloaded POST: The not-so-uniform interfaceSafety and IdempotenceSafetyIdempotenceWhy safety and idempotence matterWhy the Uniform Interface MattersThat’s It!
5. Designing Read-Only Resource-Oriented Services
Resource DesignTurning Requirements Into Read-Only ResourcesFigure Out the Data SetGeneral LessonsSplit the Data Set into ResourcesGeneral LessonsName the ResourcesEncode Hierarchy into Path VariablesNo Hierarchy? Use Commas or SemicolonsMap URIsScaleAlgorithmic Resource? Use Query VariablesURI RecapDesign Your RepresentationsThe Representation Talks About the State of the ResourceThe Representation Links to Other StatesRepresenting the List of PlanetsRepresenting Maps and Points on MapsRepresenting the Map TilesRepresenting Planets and Other PlacesRepresenting Lists of Search ResultsLink the Resources to Each OtherThe HTTP ResponseWhat’s Supposed to Happen?Conditional HTTP GETWhat Might Go Wrong?Conclusion
6. Designing Read/Write Resource-Oriented Services
User Accounts as ResourcesWhy Should User Accounts Be Resources?Authentication, Authorization, Privacy, and TrustTurning Requirements into Read/Write ResourcesFigure Out the Data SetSplit the Data Set into ResourcesName the Resources with URIsExpose a Subset of the Uniform InterfaceDesign the Representation(s) Accepted from the ClientDesign the Representation(s) to Be Served to the ClientLink This Resource to Existing ResourcesWhat’s Supposed to Happen?What Might Go Wrong?Custom PlacesFigure Out the Data SetSplit the Data Set into ResourcesName the Resources with URIsExpose a Subset of the Uniform InterfaceDesign the Representation(s) Accepted from the ClientDesign the Representation(s) Served to the ClientLink This Resource to Existing ResourcesWhat’s Supposed to Happen?What Might Go Wrong?A Look Back at the Map Service

7. A Service Implementation
A Social Bookmarking Web ServiceFiguring Out the Data SetResource DesignREST in RailsThe User ControllerThe Bookmarks ControllerThe User Tags ControllerThe Calendar ControllerThe URI ControllerThe Recent Bookmarks ControllerThe Bundles ControllerThe LeftoversRemodeling the REST WayImplementation: The routes.rb FileDesign the Representation(s) Accepted from the ClientDesign the Representation(s) Served to the ClientConnect Resources to Each OtherWhat’s Supposed to Happen?What Might Go Wrong?Controller CodeWhat Rails Doesn’t DoConditional GETparam[:id] for things that aren’t IDsThe ApplicationControllerThe UsersControllerThe BookmarksControllerThe TagsControllerThe Lesser ControllersThe CalendarControllerThe RecentControllerThe UrisControllerModel CodeThe User ModelThe Bookmark ModelWhat Does the Client Need to Know?Natural-Language Service DescriptionDescription Through StandardizationHypermedia Descriptions
8. REST and ROA Best Practices
Resource-Oriented BasicsThe Generic ROA ProcedureAddressabilityRepresentations Should Be AddressableState and StatelessnessConnectednessThe Uniform InterfaceSafety and IdempotenceNew Resources: PUT Versus POSTOverloading POSTThis Stuff MattersWhy Addressability MattersWhy Statelessness MattersWhy the Uniform Interface MattersWhy Connectedness MattersA terrifying exampleResource DesignRelationships Between ResourcesAsynchronous OperationsBatch OperationsTransactionsWhen In Doubt, Make It a ResourceURI DesignOutgoing RepresentationsIncoming RepresentationsService VersioningPermanent URIs Versus Readable URIsStandard Features of HTTPAuthentication and AuthorizationBasic authenticationDigest authenticationWSSE username tokenCompressionConditional GETCachingPlease cacheThank you for not cachingDefault caching rulesLook-Before-You-Leap RequestsPartial GETFaking PUT and DELETEThe Trouble with CookiesWhy Should a User Trust the HTTP Client?Applications with a Web InterfaceApplications with No Web InterfaceWhat Problem Does this Solve?
9. The Building Blocks of Services
Representation FormatsXHTMLXHTML with MicroformatsAtomOpenSearchSVGForm-Encoded Key-Value PairsJSONRDF and RDFaFramework-Specific Serialization FormatsAd Hoc XHTMLOther XML Standards and Ad Hoc VocabulariesEncoding IssuesXML and HTTP: Battle of the encodingsThe character encoding of a JSON documentPrepackaged Control FlowsGeneral RulesDatabase-Backed Control FlowGETPUTPOST for creating a new resourcePOST for appending to a resourceDELETEThe Atom Publishing ProtocolCollectionsMembersService documentCategory documentsBinary documents as APP membersSummaryGDataQuerying collectionsData extensionsPOST Once ExactlyHypermedia TechnologiesURI TemplatesXHTML 4XHTML 4 linksXHTML 4 formsShortcomings of XHTML 4XHTML 5WADLDescribing a del.icio.us resourceDescribing an APP collectionIs WADL evil?
10. The Resource-Oriented Architecture Versus Big Web Services
What Problems Are Big Web Services Trying to Solve?SOAPThe Resource-Oriented AlternativeWSDLThe Resource-Oriented AlternativeUDDIThe Resource-Oriented AlternativeSecurityThe Resource-Oriented AlternativeReliable MessagingThe Resource-Oriented AlternativeTransactionsThe Resource-Oriented AlternativeBPEL, ESB, and SOAConclusion
11. Ajax Applications as REST Clients
From AJAX to AjaxThe Ajax ArchitectureA del.icio.us ExampleThe Advantages of AjaxThe Disadvantages of AjaxREST Goes BetterMaking the RequestHandling the ResponseJSONDon’t Bogart the Benefits of RESTCross-Browser Issues and Ajax LibrariesPrototypeDojoSubverting the Browser Security ModelRequest ProxyingJavaScript on DemandDynamically writing the script tagLibrary support
12. Frameworks for RESTful Services
Ruby on RailsRoutingResources, Controllers, and ViewsOutgoing RepresentationsIncoming RepresentationsWeb Applications as Web ServicesThe Rails/ROA Design ProcedureRestletBasic ConceptsWriting Restlet ClientsWriting Restlet ServicesResource and URI designRequest handling and representationsCompiling, running, and testingConclusionDjangoCreate the Data ModelDefine Resources and Give Them URIsImplement Resources as Django ViewsThe bookmark list viewThe bookmark detail viewFurther directionsConclusion
A. Some Resources for REST and Some RESTful Resources
Standards and GuidesHTTP and URIRESTful ArchitecturesHypermedia FormatsFrameworks for RESTful DevelopmentWeblogs on RESTServices You Can UseService DirectoriesRead-Only ServicesRead/Write Services
B. The HTTP Response Code Top 42
Three to Seven Status Codes: The Bare Minimum1xx: Meta100 (“Continue”)101 (“Switching Protocols”)2xx: Success200 (“OK”)201 (“Created”)202 (“Accepted”)203 (“Non-Authoritative Information”)204 (“No Content”)205 (“Reset Content”)206 (“Partial Content”)207 (“Multi-Status”)3xx: Redirection300 (“Multiple Choices”)301 (“Moved Permanently”)302 (“Found”)303 (“See Other”)304 (“Not Modified”)305 (“Use Proxy”)306: Unused307 (“Temporary Redirect”)4xx: Client-Side Error400 (“Bad Request”)401 (“Unauthorized”)402 (“Payment Required”)403 (“Forbidden”)404 (“Not Found”)405 (“Method Not Allowed”)406 (“Not Acceptable”)407 (“Proxy Authentication Required”)408 (“Request Timeout”)409 (“Conflict”)410 (“Gone”)411 (“Length Required”)412 (“Precondition Failed”)413 (“Request Entity Too Large”)414 (“Request-URI Too Long”)415 (“Unsupported Media Type”)416 (“Requested Range Not Satisfiable”)417 (“Expectation Failed”)5xx: Server-Side Error500 (“Internal Server Error”)501 (“Not Implemented”)502 (“Bad Gateway”)503 (“Service Unavailable”)504 (“Gateway Timeout”)505 (“HTTP Version Not Supported”)
C. The HTTP Header Top Infinity
Standard HeadersAcceptAccept-CharsetAccept-EncodingAccept-LanguageAccept-RangesAgeAllowAuthorizationCache-ControlConnectionContent-EncodingContent-LanguageContent-LengthContent-LocationContent-MD5Content-RangeContent-TypeDateETagExpectExpiresFromHostIf-MatchIf-Modified-SinceIf-None-MatchIf-RangeIf-Unmodified-SinceLast-ModifiedLocationMax-ForwardsPragmaProxy-AuthenticateProxy-AuthorizationRangeRefererRetry-AfterTETrailerTransfer-EncodingUpgradeUser-AgentVaryViaWarningWWW-AuthenticateNonstandard HeadersCookiePOEPOE-LinksSet-CookieSlugX-HTTP-Method-OverrideX-WSSE
Index
About the Authors
Colophon
Copyright

Overview

"Every developer working with the Web needs to read this book."-- David Heinemeier Hansson, creator of the Rails framework

"RESTful Web Services finally provides a practical roadmap for constructing services that embrace the Web, instead of trying to route around it."-- Adam Trachtenberg, PHP author and EBay Web Services Evangelist

You've built web sites that can be used by humans. But can you also build web sites that are usable by machines? That's where the future lies, and that's what RESTful Web Services shows you how to do. The World Wide Web is the most popular distributed application in history, and Web services and mashups have turned it into a powerful distributed computing platform. But today's web service technologies have lost sight of the simplicity that made the Web successful. They don't work like the Web, and they're missing out on its advantages.

This book puts the "Web" back into web services. It shows how you can connect to the programmable web with the technologies you already use every day. The key is REST, the architectural style that drives the Web. This book:

Emphasizes the power of basic Web technologies -- the HTTP application protocol, the URI naming standard, and the XML markup language
Introduces the Resource-Oriented Architecture (ROA), a common-sense set of rules for designing RESTful web services
Shows how a RESTful design is simpler, more versatile, and more scalable than a design based on Remote Procedure Calls (RPC)
Includes real-world examples of RESTful web services, like Amazon's Simple Storage Service and the Atom Publishing Protocol
Discusses web service clients for popular programming languages
Shows how to implement RESTful services in three popular frameworks -- Ruby on Rails, Restlet (for Java), and Django (for Python)
Focuses on practical issues: how to design and implement RESTful web services and clients

This is the first book that applies the REST design philosophy to real web services. It sets down the best practices you need to make your design a success, and the techniques you need to turn your design into working code. You can harness the power of the Web for programmable applications: you just have to work with the Web instead of against it. This book shows you how.

Become an O’Reilly member and get unlimited access to this title plus top books and audiobooks from O’Reilly and nearly 200 top publishers, thousands of courses curated by job role, 150+ live events each month,
and much more.

Read now

Unlock full access

More than 5,000 organizations count on O’Reilly

O’Reilly covers everything we've got, with content to help us build a world-class technology community, upgrade the capabilities and competencies of our teams, and improve overall team performance as well as their engagement.

Julian F.

Head of Cybersecurity

I wanted to learn C and C++, but it didn't click for me until I picked up an O'Reilly book. When I went on the O’Reilly platform, I was astonished to find all the books there, plus live events and sandboxes so you could play around with the technology.

Addison B.

Field Engineer

I’ve been on the O’Reilly platform for more than eight years. I use a couple of learning platforms, but I'm on O'Reilly more than anybody else. When you're there, you start learning. I'm never disappointed.

Amir M.

Data Platform Tech Lead

I'm always learning. So when I got on to O'Reilly, I was like a kid in a candy store. There are playlists. There are answers. There's on-demand training. It's worth its weight in gold, in terms of what it allows me to do.

Mark W.

Embedded Software Engineer

RESTful Java Web Services - Third Edition

Publisher Resources

ISBN: 9780596529260Errata Page

Cloud Computing

Data Engineering

Data Science

AI & ML

Programming Languages

Software Architecture

IT/Ops

Security

Design

Business

Soft Skills