Cover image for RESTful Web Services Cookbook

Book description

RESTful web services may be simpler, more versatile, and more scalable than web services built with SOAP or CORBA, but using the REST architecture is still no picnic. In this cookbook, you'll get more than 50 recipes to help you solve common problems you're likely to face when designing and developing RESTful web services. These recipes are applicable no matter what programming language you use. Just browse through the book to find the answers you need. The recipes are illustrated using HTTP requests and responses, XML, JSON, Atom snippets, sequence diagrams of client-server interactions, and resource models. Some recipes offer more than one solution to a problem, and include a detailed discussion of the tradeoffs involved in choosing which solution to use. Each recipe includes easy-to-follow, step-by-step instructions. RESTful Web Services Cookbook is still in progress, but you can start using the recipes with our Rough Cuts edition, which lets you read the book as it's being written, either online or via PDF.

Table of Contents

  1. RESTful Web Services Cookbook
    1. SPECIAL OFFER: Upgrade this ebook with O’Reilly
    2. Preface
      1. Scope of the Book
      2. Companion Material
      3. How This Book Is Organized
      4. Conventions Used in This Book
      5. Using Code Examples
      6. Safari® Books Online
      7. How to Contact Us
      8. Acknowledgments
      9. Mike Amundsen’s Contribution
    3. 1. Using the Uniform Interface
      1. 1.1. How to Keep Interactions Visible
        1. Problem
        2. Solution
        3. Discussion
      2. 1.2. When to Trade Visibility
        1. Problem
        2. Solution
        3. Discussion
      3. 1.3. How to Maintain Application State
        1. Problem
        2. Solution
        3. Discussion
      4. 1.4. How to Implement Safe and Idempotent Methods on the Server
        1. Problem
        2. Solution
        3. Discussion
          1. Implementing safe methods
          2. Implementing idempotent methods
          3. Idempotency of DELETE
      5. 1.5. How to Treat Safe and Idempotent Methods in Clients
        1. Problem
        2. Solution
        3. Discussion
          1. Safe methods
          2. Idempotent methods
      6. 1.6. When to Use GET
        1. Problem
        2. Solution
        3. Discussion
      7. 1.7. When to Use POST
        1. Problem
        2. Solution
        3. Discussion
      8. 1.8. How to Create Resources Using POST
        1. Problem
        2. Solution
        3. Discussion
      9. 1.9. When to Use PUT to Create New Resources
        1. Problem
        2. Solution
        3. Discussion
      10. 1.10. How to Use POST for Asynchronous Tasks
        1. Problem
        2. Solution
        3. Discussion
      11. 1.11. How to Use DELETE for Asynchronous Deletion
        1. Problem
        2. Solution
        3. Discussion
      12. 1.12. When to Use Custom HTTP Methods
        1. Problem
        2. Solution
        3. Discussion
      13. 1.13. When and How to Use Custom HTTP Headers
        1. Problem
        2. Solution
        3. Discussion
    4. 2. Identifying Resources
      1. 2.1. How to Identify Resources from Domain Nouns
        1. Problem
        2. Solution
        3. Discussion
      2. 2.2. How to Choose Resource Granularity
        1. Problem
        2. Solution
        3. Discussion
      3. 2.3. How to Organize Resources into Collections
        1. Problem
        2. Solution
        3. Discussion
      4. 2.4. When to Combine Resources into Composites
        1. Problem
        2. Solution
        3. Discussion
      5. 2.5. How to Support Computing/Processing Functions
        1. Problem
        2. Solution
        3. Discussion
      6. 2.6. When and How to Use Controllers to Operate on Resources
        1. Problem
        2. Solution
        3. Discussion
    5. 3. Designing Representations
      1. 3.1. How to Use Entity Headers to Annotate Representations
        1. Problem
        2. Solution
        3. Discussion
          1. Content-Type
          2. Content-Length
          3. Content-Language
          4. Content-MD5
          5. Content-Encoding
          6. Last-Modified
      2. 3.2. How to Interpret Entity Headers
        1. Problem
        2. Solution
        3. Discussion
      3. 3.3. How to Avoid Character Encoding Mismatch
        1. Problem
        2. Solution
        3. Discussion
      4. 3.4. How to Choose a Representation Format and a Media Type
        1. Problem
        2. Solution
        3. Discussion
          1. Using standard or well-known media types
          2. Introducing new formats and media types
      5. 3.5. How to Design XML Representations
        1. Problem
        2. Solution
        3. Discussion
      6. 3.6. How to Design JSON Representations
        1. Problem
        2. Solution
        3. Discussion
      7. 3.7. How to Design Representations of Collections
        1. Problem
        2. Solution
        3. Discussion
      8. 3.8. How to Keep Collections Homogeneous
        1. Problem
        2. Solution
        3. Discussion
      9. 3.9. How to Use Portable Data Formats in Representations
        1. Problem
        2. Solution
        3. Discussion
          1. Numbers
          2. Countries and territories
          3. Currencies
          4. Dates and times
          5. Language tags
          6. Time zone identifiers
      10. 3.10. When to Use Entity Identifiers
        1. Problem
        2. Solution
        3. Discussion
      11. 3.11. How to Encode Binary Data in Representations
        1. Problem
        2. Solution
        3. Discussion
      12. 3.12. When and How to Serve HTML Representations
        1. Problem
        2. Solution
        3. Discussion
      13. 3.13. How to Return Errors
        1. Problem
        2. Solution
        3. Discussion
          1. Errors due to client inputs: 4xx
          2. Errors due to server errors: 5xx
          3. Message body for errors
      14. 3.14. How to Treat Errors in Clients
        1. Problem
        2. Solution
        3. Discussion
    6. 4. Designing URIs
      1. 4.1. How to Design URIs
        1. Problem
        2. Solution
        3. Discussion
          1. Domains and subdomains
          2. Forward-slash separator
          3. Underscore and hyphen
          4. Ampersand
          5. Comma and semicolon
          6. Full stop, or period
          7. Implementation-specific file extensions
          8. Spaces and capital letters
      2. 4.2. How to Use URIs As Opaque Identifiers
        1. Problem
        2. Solution
        3. Discussion
      3. 4.3. How to Let Clients Treat URIs As Opaque Identifiers
        1. Problem
        2. Solution
        3. Discussion
      4. 4.4. How to Keep URIs Cool
        1. Problem
        2. Solution
        3. Discussion
    7. 5. Web Linking
      1. 5.1. How to Use Links in XML Representations
        1. Problem
        2. Solution
        3. Discussion
      2. 5.2. How to Use Links in JSON Representations
        1. Problem
        2. Solution
        3. Discussion
      3. 5.3. When and How to Use Link Headers
        1. Problem
        2. Solution
        3. Discussion
      4. 5.4. How to Assign Link Relation Types
        1. Problem
        2. Solution
        3. Discussion
      5. 5.5. How to Use Links to Manage Application Flow
        1. Problem
        2. Solution
        3. Discussion
      6. 5.6. How to Deal with Ephemeral URIs
        1. Problem
        2. Solution
        3. Discussion
      7. 5.7. When and How to Use URI Templates
        1. Problem
        2. Solution
        3. Discussion
      8. 5.8. How to Use Links in Clients
        1. Problem
        2. Solution
        3. Discussion
    8. 6. Atom and AtomPub
      1. 6.1. How to Model Resources Using Atom
        1. Problem
        2. Solution
        3. Discussion
      2. 6.2. When to Use Atom
        1. Problem
        2. Solution
        3. Discussion
      3. 6.3. How to Use AtomPub Service and Category Documents
        1. Problem
        2. Solution
        3. Discussion
      4. 6.4. How to Use AtomPub for Feed and Entry Resources
        1. Problem
        2. Solution
        3. Discussion
      5. 6.5. How to Use Media Resources
        1. Problem
        2. Solution
        3. Discussion
    9. 7. Content Negotiation
      1. 7.1. How to Indicate Client Preferences
        1. Problem
        2. Solution
        3. Discussion
      2. 7.2. How to Implement Media Type Negotiation
        1. Problem
        2. Solution
        3. Discussion
      3. 7.3. How to Implement Language Negotiation
        1. Problem
        2. Solution
        3. Discussion
      4. 7.4. How to Implement Character Encoding Negotiation
        1. Problem
        2. Solution
        3. Discussion
      5. 7.5. How to Support Compression
        1. Problem
        2. Solution
        3. Discussion
      6. 7.6. When and How to Send the Vary Header
        1. Problem
        2. Solution
        3. Discussion
      7. 7.7. How to Handle Negotiation Failures
        1. Problem
        2. Solution
        3. Discussion
      8. 7.8. How to Use Agent-Driven Content Negotiation
        1. Problem
        2. Solution
        3. Discussion
      9. 7.9. When to Support Server-Driven Negotiation
        1. Problem
        2. Solution
        3. Discussion
    10. 8. Queries
      1. 8.1. How to Design URIs for Queries
        1. Problem
        2. Solution
        3. Discussion
      2. 8.2. How to Design Query Responses
        1. Problem
        2. Solution
        3. Discussion
      3. 8.3. How to Support Query Requests with Large Inputs
        1. Problem
        2. Solution
        3. Discussion
      4. 8.4. How to Store Queries
        1. Problem
        2. Solution
        3. Discussion
    11. 9. Web Caching
      1. 9.1. How to Set Expiration Caching Headers
        1. Problem
        2. Solution
        3. Discussion
      2. 9.2. When to Set Expiration Caching Headers
        1. Problem
        2. Solution
        3. Discussion
      3. 9.3. When and How to Use Expiration Headers in Clients
        1. Problem
        2. Solution
        3. Discussion
      4. 9.4. How to Support Caching for Composite Resources
        1. Problem
        2. Solution
        3. Discussion
      5. 9.5. How to Keep Caches Fresh and Warm
        1. Problem
        2. Solution
        3. Discussion
    12. 10. Conditional Requests
      1. 10.1. How to Generate Last-Modified and ETag Headers
        1. Problem
        2. Solution
        3. Discussion
      2. 10.2. How to Implement Conditional GET Requests in Servers
        1. Problem
        2. Solution
        3. Discussion
      3. 10.3. How to Submit Conditional GET and HEAD Requests from Clients
        1. Problem
        2. Solution
        3. Discussion
      4. 10.4. How to Implement Conditional PUT Requests in Servers
        1. Problem
        2. Solution
        3. Discussion
      5. 10.5. How to Implement Conditional DELETE Requests in Servers
        1. Problem
        2. Solution
        3. Discussion
      6. 10.6. How to Make Unconditional GET Requests from Clients
        1. Problem
        2. Solution
        3. Discussion
      7. 10.7. How to Submit Conditional PUT and DELETE Requests from Clients
        1. Problem
        2. Solution
        3. Discussion
      8. 10.8. How to Make POST Requests Conditional
        1. Problem
        2. Solution
        3. Discussion
      9. 10.9. How to Generate One-Time URIs
        1. Problem
        2. Solution
        3. Discussion
    13. 11. Miscellaneous Writes
      1. 11.1. How to Copy a Resource
        1. Problem
        2. Solution
        3. Discussion
      2. 11.2. How to Merge Resources
        1. Problem
        2. Solution
        3. Discussion
      3. 11.3. How to Move a Resource
        1. Problem
        2. Solution
        3. Discussion
      4. 11.4. When to Use WebDAV Methods
        1. Problem
        2. Solution
        3. Discussion
      5. 11.5. How to Support Operations Across Servers
        1. Problem
        2. Solution
        3. Discussion
      6. 11.6. How to Take Snapshots of Resources
        1. Problem
        2. Solution
        3. Discussion
      7. 11.7. How to Undo Resource Updates
        1. Problem
        2. Solution
        3. Discussion
      8. 11.8. How to Refine Resources for Partial Updates
        1. Problem
        2. Solution
        3. Discussion
      9. 11.9. How to Use the PATCH Method
        1. Problem
        2. Solution
        3. Discussion
      10. 11.10. How to Process Similar Resources in Bulk
        1. Problem
        2. Solution
        3. Discussion
      11. 11.11. How to Trigger Bulk Operations
        1. Problem
        2. Solution
        3. Discussion
      12. 11.12. When to Tunnel Multiple Requests Using POST
        1. Problem
        2. Solution
        3. Discussion
      13. 11.13. How to Support Batch Requests
        1. Problem
        2. Solution
        3. Discussion
      14. 11.14. How to Support Transactions
        1. Problem
        2. Solution
        3. Discussion
    14. 12. Security
      1. 12.1. How to Use Basic Authentication to Authenticate Clients
        1. Problem
        2. Solution
        3. Discussion
      2. 12.2. How to Use Digest Authentication to Authenticate Clients
        1. Problem
        2. Solution
        3. Discussion
      3. 12.3. How to Use Three-Legged OAuth
        1. Problem
        2. Solution
        3. Discussion
      4. 12.4. How to Use Two-Legged OAuth
        1. Problem
        2. Solution
        3. Discussion
      5. 12.5. How to Deal with Sensitive Information in URIs
        1. Problem
        2. Solution
        3. Discussion
      6. 12.6. How to Maintain the Confidentiality and Integrity of Representations
        1. Problem
        2. Solution
        3. Discussion
    15. 13. Extensibility and Versioning
      1. 13.1. How to Maintain URI Compatibility
        1. Problem
        2. Solution
        3. Discussion
      2. 13.2. How to Maintain Compatibility of XML and JSON Representations
        1. Problem
        2. Solution
        3. Discussion
      3. 13.3. How to Extend Atom
        1. Problem
        2. Solution
        3. Discussion
      4. 13.4. How to Maintain Compatibility of Links
        1. Problem
        2. Solution
        3. Discussion
      5. 13.5. How to Implement Clients to Support Extensibility
        1. Problem
        2. Solution
        3. Discussion
      6. 13.6. When to Version
        1. Problem
        2. Solution
        3. Discussion
      7. 13.7. How to Version RESTful Web Services
        1. Problem
        2. Solution
        3. Discussion
    16. 14. Enabling Discovery
      1. 14.1. How to Document RESTful Web Services
        1. Problem
        2. Solution
        3. Discussion
      2. 14.2. How to Use OPTIONS
        1. Problem
        2. Solution
        3. Discussion
    17. A. Additional Reading
      1. Books
      2. References
        1. Foundation
        2. Atom and AtomPub
        3. Caching
        4. Formats and Media Types
        5. Security
    18. B. Overview of REST
      1. Uniform Resource Identifiers
      2. Resources
      3. Representations
      4. Uniform Interface
      5. Hypermedia and Application State
    19. C. HTTP Methods
      1. OPTIONS
      2. GET
      3. HEAD
      4. POST
      5. PUT
      6. DELETE
      7. TRACE
    20. D. Atom Syndication Format
      1. Key Elements of Feeds and Entries
        1. atom:author
        2. atom:content and atom:summary
        3. atom:id
        4. atom:link
        5. atom:title
        6. atom:updated
      2. Other Atom Elements to Consider
        1. atom:category
        2. atom:contributor
        3. atom:generator
        4. atom:icon
        5. atom:logo
        6. atom:published
        7. atom:rights
        8. atom:subtitle
    21. E. Link Relation Registry
      1. alternate
      2. appendix
      3. bookmark
      4. chapter, section, subsection
      5. contents
      6. copyright
      7. current
      8. describedby
      9. edit
      10. edit-media
      11. enclosure
      12. first, last, next, next-archive, prev, previous, prev-archive, start
      13. glossary
      14. help
      15. index
      16. license
      17. payment
      18. related
      19. replies
      20. self
      21. service
      22. stylesheet
      23. up
      24. via
    22. Index
    23. About the Author
    24. Colophon
    25. SPECIAL OFFER: Upgrade this ebook with O’Reilly