You are previewing RESTful Web Services.
O'Reilly logo
RESTful Web Services

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.

Table of Contents

  1. RESTful Web Services
    1. SPECIAL OFFER: Upgrade this ebook with O’Reilly
    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. SPECIAL OFFER: Upgrade this ebook with O’Reilly