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 10. The Resource-Oriented Architecture Versus Big Web Services

Throughout this book I’ve focused on technologies and architectures that work with the grain of the Web. I’ve shown you how to arrange resources into services that are very powerful, but conceptually simple and accessible from a wide variety of standard clients. But I’ve hardly said a word about the technologies that most people think of when they think web services: SOAP, WSDL, and the WS-* stack. These technologies form a competing paradigm for web services: one that doesn’t really work like the Web. Rather than letting these technologies claim the entire field of web services for themselves, I’ve given them a not entirely kind, but fairly mild nickname: Big Web Services. In this chapter I’ll compare the two paradigms.

The web is based on resources, but Big Web Services don’t expose resources. The Web is based on URIs and links, but a typical Big Web Service exposes one URI and zero links. The Web is based on HTTP, and Big Web Services hardly use HTTP’s features at all. This isn’t academic hair-splitting, because it means Big Web Services don’t get the benefits of resource-oriented web services. They’re not addressable, cacheable, or well connected, and they don’t respect any uniform interface. (Many of them are stateless, though.) They’re opaque, and understanding one doesn’t help you understand the next one. In practice, they also tend to have interoperability problems when serving a variety of clients.

In ...