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 12. Frameworks for RESTful Services

As the REST design philosophy becomes more popular, new frameworks are springing up to make RESTful design easy. Existing frameworks are acquiring RESTful modes and features. This, in turn, drives additional interest in REST. In this chapter, I and a few knowledgeable contributors show you how to write resource-oriented services in three popular frameworks: Ruby on Rails, Restlet (for Java), and Django (for Python).

Back in Chapter 1 I said that REST isn’t an architecture, but a way of judging architectures. The Resource-Oriented Architecture is an architecture: it imposes constraints on your thinking that make it easy for you to break a problem down into RESTful resources. But these resources still only exist on an abstract level. They aren’t real until you expose them through specific web services.

If you’re writing a service from scratch (say, as a CGI script), you can translate your resources into code however you like. But most services aren’t written from scratch: they’re written using a web framework. A REST-aware web framework imposes constraints on your programming that make it easy for you to implement RESTful resources in a specific programming language. In this chapter I’ll show you how to integrate the lessons of this book with real frameworks.

Ruby on Rails

The simplifying assumption is the main driver of the success of Ruby on Rails. Rather than give you a large number of tools for accomplishing any task you can think of, Rails ...