book

RESTful Web Services

by Leonard Richardson, Sam Ruby

May 2007

Intermediate to advanced

446 pages

14h 31m

English

O'Reilly Media, Inc.

Read now

Unlock full access

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
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
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
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
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!
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
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

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
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?
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?
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
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
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
Standards and GuidesHTTP and URIRESTful ArchitecturesHypermedia FormatsFrameworks for RESTful DevelopmentWeblogs on RESTServices You Can UseService DirectoriesRead-Only ServicesRead/Write Services
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”)
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

Content preview from RESTful Web Services

Colophon

Our look is the result of reader comments, our own experimentation, and feedback from distribution channels. Distinctive covers complement our distinctive approach to technical topics, breathing personality and life into potentially dry subjects.

The animal on the cover of RESTful Web Services is a vulpine phalanger (P. vulpina). Phalanger is the general term given to animals of the Phalangeridae family, which includes possums and cuscuses. (One should not confuse the Australian possum with the American opossum; they are both marsupials, but very different.) The term phalanger is derived from the Greek word phalanges, which means finger or toe bone. The omnivorous phalanger uses its claw-fingered paws (with opposable thumbs) to climb, hunt, and live in trees. Phalangers are found in the forests of Australia, New Zealand, Tasmania, and some Indonesian islands. Like the most famous marsupial, the kangaroo, female phalangers carry their young around in a front pouch after birth.

Phalanger is also the name of a PHP complier project for the .NET framework.

The cover image is from Wood’s Natural History. The cover font is Adobe ITC Garamond. The text font is Linotype Birka; the heading font is Adobe Myriad Condensed; and the code font is LucasFont’s TheSans Mono Condensed.