RESTful Web Services

RESTful Web Services

by Leonard Richardson, Sam Ruby
Released May 2007
Publisher(s): O'Reilly Media, Inc.
ISBN: 9780596529260

Read it now on the O’Reilly learning platform with a 10-day free trial.

O’Reilly members get unlimited access to books, live events, courses curated by job role, and more from O’Reilly and nearly 200 top publishers.

Buy on Amazon
Start your free trial

Book description

"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.

Publisher resources

View/Submit Errata

Table of contents

  1. Dedication
  2. A Note Regarding Supplemental Files
  3. Foreword
  4. Preface
    1. The Web Is Simple
    2. Big Web Services Are Not Simple
    3. The Story of the REST
    4. Reuniting the Webs
    5. What’s in This Book?
    6. Administrative Notes
    7. Conventions Used in This Book
    8. Using Code Examples
    9. Safari® Enabled
    10. How to Contact Us
    11. Acknowledgments
  5. 1. The Programmable Web and Its Inhabitants
    1. Kinds of Things on the Programmable Web
    2. HTTP: Documents in Envelopes
    3. Method Information
    4. Scoping Information
    5. The Competing Architectures
      1. RESTful, Resource-Oriented Architectures
      2. RPC-Style Architectures
      3. REST-RPC Hybrid Architectures
      4. The Human Web Is on the Programmable Web
    6. Technologies on the Programmable Web
      1. HTTP
      2. URI
      3. XML-RPC
      4. SOAP
      5. WS-*
      6. WSDL
      7. WADL
    7. Leftover Terminology
  6. 2. Writing Web Service Clients
    1. Web Services Are Web Sites
      1. Wrappers, WADL, and ActiveResource
    2. del.icio.us: The Sample Application
      1. What the Sample Clients Do
    3. Making the Request: HTTP Libraries
      1. Optional Features
      2. Ruby: rest-open-uri and net/http
      3. Python: httplib2
      4. Java: HttpClient
      5. C#: System.Web.HTTPWebRequest
      6. PHP: libcurl
      7. JavaScript: XMLHttpRequest
      8. The Command Line: curl
      9. Other Languages
    4. Processing the Response: XML Parsers
      1. Ruby: REXML, I Guess
      2. Python: ElementTree
      3. Java: javax.xml, Xerces, or XMLPull
      4. C#: System.Xml.XmlReader
      5. PHP
      6. JavaScript: responseXML
      7. Other Languages
    5. JSON Parsers: Handling Serialized Data
    6. Clients Made Easy with WADL
  7. 3. What Makes RESTful Services Different?
    1. Introducing the Simple Storage Service
    2. Object-Oriented Design of S3
      1. A Few Words About Buckets
      2. A Few Words About Objects
      3. What If S3 Was a Standalone Library?
    3. Resources
    4. HTTP Response Codes
    5. An S3 Client
      1. The Bucket List
      2. The Bucket
      3. The S3 Object
    6. Request Signing and Access Control
      1. Signing a URI
      2. Setting Access Policy
    7. Using the S3 Client Library
    8. Clients Made Transparent with ActiveResource
      1. Creating a Simple Service
      2. An ActiveResource Client
      3. A Python Client for the Simple Service
    9. Parting Words
  8. 4. The Resource-Oriented Architecture
    1. Resource-Oriented What Now?
    2. What’s a Resource?
    3. URIs
      1. URIs Should Be Descriptive
      2. The Relationship Between URIs and Resources
    4. Addressability
    5. Statelessness
      1. Application State Versus Resource State
    6. Representations
      1. Deciding Between Representations
    7. Links and Connectedness
    8. The Uniform Interface
      1. GET, PUT, and DELETE
      2. HEAD and OPTIONS
      3. POST
        1. Creating subordinate resources
        2. Appending to the resource state
        3. Overloaded POST: The not-so-uniform interface
      4. Safety and Idempotence
        1. Safety
        2. Idempotence
        3. Why safety and idempotence matter
      5. Why the Uniform Interface Matters
    9. That’s It!
  9. 5. Designing Read-Only Resource-Oriented Services
    1. Resource Design
    2. Turning Requirements Into Read-Only Resources
    3. Figure Out the Data Set
      1. General Lessons
    4. Split the Data Set into Resources
      1. General Lessons
    5. Name the Resources
      1. Encode Hierarchy into Path Variables
      2. No Hierarchy? Use Commas or Semicolons
        1. Map URIs
        2. Scale
      3. Algorithmic Resource? Use Query Variables
      4. URI Recap
    6. Design Your Representations
      1. The Representation Talks About the State of the Resource
      2. The Representation Links to Other States
      3. Representing the List of Planets
      4. Representing Maps and Points on Maps
      5. Representing the Map Tiles
      6. Representing Planets and Other Places
      7. Representing Lists of Search Results
    7. Link the Resources to Each Other
    8. The HTTP Response
      1. What’s Supposed to Happen?
        1. Conditional HTTP GET
      2. What Might Go Wrong?
    9. Conclusion
  10. 6. Designing Read/Write Resource-Oriented Services
    1. User Accounts as Resources
      1. Why Should User Accounts Be Resources?
      2. Authentication, Authorization, Privacy, and Trust
      3. Turning Requirements into Read/Write Resources
      4. Figure Out the Data Set
      5. Split the Data Set into Resources
      6. Name the Resources with URIs
      7. Expose a Subset of the Uniform Interface
      8. Design the Representation(s) Accepted from the Client
      9. Design the Representation(s) to Be Served to the Client
      10. Link This Resource to Existing Resources
      11. What’s Supposed to Happen?
      12. What Might Go Wrong?
    2. Custom Places
      1. Figure Out the Data Set
      2. Split the Data Set into Resources
      3. Name the Resources with URIs
      4. Expose a Subset of the Uniform Interface
      5. Design the Representation(s) Accepted from the Client
      6. Design the Representation(s) Served to the Client
      7. Link This Resource to Existing Resources
      8. What’s Supposed to Happen?
      9. What Might Go Wrong?
    3. A Look Back at the Map Service
  11. 7. A Service Implementation
    1. A Social Bookmarking Web Service
    2. Figuring Out the Data Set
    3. Resource Design
      1. REST in Rails
      2. The User Controller
      3. The Bookmarks Controller
      4. The User Tags Controller
      5. The Calendar Controller
      6. The URI Controller
      7. The Recent Bookmarks Controller
      8. The Bundles Controller
      9. The Leftovers
      10. Remodeling the REST Way
      11. Implementation: The routes.rb File
    4. Design the Representation(s) Accepted from the Client
    5. Design the Representation(s) Served to the Client
    6. Connect Resources to Each Other
    7. What’s Supposed to Happen?
    8. What Might Go Wrong?
    9. Controller Code
      1. What Rails Doesn’t Do
        1. Conditional GET
        2. param[:id] for things that aren’t IDs
      2. The ApplicationController
      3. The UsersController
      4. The BookmarksController
      5. The TagsController
      6. The Lesser Controllers
        1. The CalendarController
        2. The RecentController
        3. The UrisController
    10. Model Code
      1. The User Model
      2. The Bookmark Model
    11. What Does the Client Need to Know?
      1. Natural-Language Service Description
      2. Description Through Standardization
      3. Hypermedia Descriptions
  12. 8. REST and ROA Best Practices
    1. Resource-Oriented Basics
    2. The Generic ROA Procedure
    3. Addressability
      1. Representations Should Be Addressable
    4. State and Statelessness
    5. Connectedness
    6. The Uniform Interface
      1. Safety and Idempotence
      2. New Resources: PUT Versus POST
      3. Overloading POST
    7. This Stuff Matters
      1. Why Addressability Matters
      2. Why Statelessness Matters
      3. Why the Uniform Interface Matters
      4. Why Connectedness Matters
        1. A terrifying example
    8. Resource Design
      1. Relationships Between Resources
      2. Asynchronous Operations
      3. Batch Operations
      4. Transactions
      5. When In Doubt, Make It a Resource
    9. URI Design
    10. Outgoing Representations
    11. Incoming Representations
    12. Service Versioning
    13. Permanent URIs Versus Readable URIs
    14. Standard Features of HTTP
      1. Authentication and Authorization
        1. Basic authentication
        2. Digest authentication
        3. WSSE username token
      2. Compression
      3. Conditional GET
      4. Caching
        1. Please cache
        2. Thank you for not caching
        3. Default caching rules
      5. Look-Before-You-Leap Requests
      6. Partial GET
    15. Faking PUT and DELETE
    16. The Trouble with Cookies
    17. Why Should a User Trust the HTTP Client?
      1. Applications with a Web Interface
      2. Applications with No Web Interface
      3. What Problem Does this Solve?
  13. 9. The Building Blocks of Services
    1. Representation Formats
      1. XHTML
      2. XHTML with Microformats
      3. Atom
        1. OpenSearch
      4. SVG
      5. Form-Encoded Key-Value Pairs
      6. JSON
      7. RDF and RDFa
      8. Framework-Specific Serialization Formats
      9. Ad Hoc XHTML
      10. Other XML Standards and Ad Hoc Vocabularies
      11. Encoding Issues
        1. XML and HTTP: Battle of the encodings
        2. The character encoding of a JSON document
    2. Prepackaged Control Flows
      1. General Rules
      2. Database-Backed Control Flow
        1. GET
        2. PUT
        3. POST for creating a new resource
        4. POST for appending to a resource
        5. DELETE
      3. The Atom Publishing Protocol
        1. Collections
        2. Members
        3. Service document
        4. Category documents
        5. Binary documents as APP members
        6. Summary
      4. GData
        1. Querying collections
        2. Data extensions
      5. POST Once Exactly
    3. Hypermedia Technologies
      1. URI Templates
      2. XHTML 4
        1. XHTML 4 links
        2. XHTML 4 forms
        3. Shortcomings of XHTML 4
      3. XHTML 5
      4. WADL
        1. Describing a del.icio.us resource
        2. Describing an APP collection
        3. Is WADL evil?
  14. 10. The Resource-Oriented Architecture Versus Big Web Services
    1. What Problems Are Big Web Services Trying to Solve?
    2. SOAP
      1. The Resource-Oriented Alternative
    3. WSDL
      1. The Resource-Oriented Alternative
    4. UDDI
      1. The Resource-Oriented Alternative
    5. Security
      1. The Resource-Oriented Alternative
    6. Reliable Messaging
      1. The Resource-Oriented Alternative
    7. Transactions
      1. The Resource-Oriented Alternative
    8. BPEL, ESB, and SOA
    9. Conclusion
  15. 11. Ajax Applications as REST Clients
    1. From AJAX to Ajax
    2. The Ajax Architecture
    3. A del.icio.us Example
    4. The Advantages of Ajax
    5. The Disadvantages of Ajax
    6. REST Goes Better
    7. Making the Request
    8. Handling the Response
    9. JSON
    10. Don’t Bogart the Benefits of REST
    11. Cross-Browser Issues and Ajax Libraries
      1. Prototype
      2. Dojo
    12. Subverting the Browser Security Model
      1. Request Proxying
      2. JavaScript on Demand
        1. Dynamically writing the script tag
        2. Library support
  16. 12. Frameworks for RESTful Services
    1. Ruby on Rails
      1. Routing
      2. Resources, Controllers, and Views
      3. Outgoing Representations
      4. Incoming Representations
      5. Web Applications as Web Services
      6. The Rails/ROA Design Procedure
    2. Restlet
      1. Basic Concepts
      2. Writing Restlet Clients
      3. Writing Restlet Services
        1. Resource and URI design
        2. Request handling and representations
        3. Compiling, running, and testing
      4. Conclusion
    3. Django
      1. Create the Data Model
      2. Define Resources and Give Them URIs
      3. Implement Resources as Django Views
        1. The bookmark list view
        2. The bookmark detail view
        3. Further directions
      4. Conclusion
  17. A. Some Resources for REST and Some RESTful Resources
    1. Standards and Guides
      1. HTTP and URI
      2. RESTful Architectures
      3. Hypermedia Formats
      4. Frameworks for RESTful Development
      5. Weblogs on REST
    2. Services You Can Use
      1. Service Directories
      2. Read-Only Services
      3. Read/Write Services
  18. B. The HTTP Response Code Top 42
    1. Three to Seven Status Codes: The Bare Minimum
    2. 1xx: Meta
      1. 100 (“Continue”)
      2. 101 (“Switching Protocols”)
    3. 2xx: Success
      1. 200 (“OK”)
      2. 201 (“Created”)
      3. 202 (“Accepted”)
      4. 203 (“Non-Authoritative Information”)
      5. 204 (“No Content”)
      6. 205 (“Reset Content”)
      7. 206 (“Partial Content”)
      8. 207 (“Multi-Status”)
    4. 3xx: Redirection
      1. 300 (“Multiple Choices”)
      2. 301 (“Moved Permanently”)
      3. 302 (“Found”)
      4. 303 (“See Other”)
      5. 304 (“Not Modified”)
      6. 305 (“Use Proxy”)
      7. 306: Unused
      8. 307 (“Temporary Redirect”)
    5. 4xx: Client-Side Error
      1. 400 (“Bad Request”)
      2. 401 (“Unauthorized”)
      3. 402 (“Payment Required”)
      4. 403 (“Forbidden”)
      5. 404 (“Not Found”)
      6. 405 (“Method Not Allowed”)
      7. 406 (“Not Acceptable”)
      8. 407 (“Proxy Authentication Required”)
      9. 408 (“Request Timeout”)
      10. 409 (“Conflict”)
      11. 410 (“Gone”)
      12. 411 (“Length Required”)
      13. 412 (“Precondition Failed”)
      14. 413 (“Request Entity Too Large”)
      15. 414 (“Request-URI Too Long”)
      16. 415 (“Unsupported Media Type”)
      17. 416 (“Requested Range Not Satisfiable”)
      18. 417 (“Expectation Failed”)
    6. 5xx: Server-Side Error
      1. 500 (“Internal Server Error”)
      2. 501 (“Not Implemented”)
      3. 502 (“Bad Gateway”)
      4. 503 (“Service Unavailable”)
      5. 504 (“Gateway Timeout”)
      6. 505 (“HTTP Version Not Supported”)
  19. C. The HTTP Header Top Infinity
    1. Standard Headers
      1. Accept
      2. Accept-Charset
      3. Accept-Encoding
      4. Accept-Language
      5. Accept-Ranges
      6. Age
      7. Allow
      8. Authorization
      9. Cache-Control
      10. Connection
      11. Content-Encoding
      12. Content-Language
      13. Content-Length
      14. Content-Location
      15. Content-MD5
      16. Content-Range
      17. Content-Type
      18. Date
      19. ETag
      20. Expect
      21. Expires
      22. From
      23. Host
      24. If-Match
      25. If-Modified-Since
      26. If-None-Match
      27. If-Range
      28. If-Unmodified-Since
      29. Last-Modified
      30. Location
      31. Max-Forwards
      32. Pragma
      33. Proxy-Authenticate
      34. Proxy-Authorization
      35. Range
      36. Referer
      37. Retry-After
      38. TE
      39. Trailer
      40. Transfer-Encoding
      41. Upgrade
      42. User-Agent
      43. Vary
      44. Via
      45. Warning
      46. WWW-Authenticate
    2. Nonstandard Headers
      1. Cookie
      2. POE
      3. POE-Links
      4. Set-Cookie
      5. Slug
      6. X-HTTP-Method-Override
      7. X-WSSE
  20. Index
  21. About the Authors
  22. Colophon
  23. Copyright

Product information

  • Title: RESTful Web Services
  • Author(s): Leonard Richardson, Sam Ruby
  • Release date: May 2007
  • Publisher(s): O'Reilly Media, Inc.
  • ISBN: 9780596529260