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

Chapter 3. What Makes RESTful Services Different?

I pulled a kind of bait-and-switch on you earlier, and it’s time to make things right. Though this is a book about RESTful web services, most of the real services I’ve shown you are REST-RPC hybrids like the del.icio.us API: services that don’t quite work like the rest of the Web. This is because right now, there just aren’t many well-known RESTful services that work like the Web. In previous chapters I wanted to show you clients for real services you might have heard of, so I had to take what I could get.

The del.icio.us and Flickr APIs are good examples of hybrid services. They work like the Web when you’re fetching data, but they’re RPC-style services when it comes time to modify the data. The various Yahoo! search services are very RESTful, but they’re so simple that they don’t make good examples. The Amazon E-Commerce Service (seen in Example 1-2) is also quite simple, and defects to the RPC style on a few obscure but important points.

These services are all useful. I think the RPC style is the wrong one for web services, but that never prevents me from writing an RPC-style client if there’s interesting data on the other side. I can’t use Flickr or the del.icio.us API as examples of how to design RESTful web services, though. That’s why I covered them early in the book, when the only thing I was trying to show was what’s on the programmable web and how to write HTTP clients. Now that we’re approaching a heavy design chapter, I ...