You are previewing RESTful Web Services Cookbook.

RESTful Web Services Cookbook

Cover of RESTful Web Services Cookbook by Subbu Allamaraju Published by O'Reilly Media, Inc.
  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
      2. 1.2. When to Trade Visibility
      3. 1.3. How to Maintain Application State
      4. 1.4. How to Implement Safe and Idempotent Methods on the Server
      5. 1.5. How to Treat Safe and Idempotent Methods in Clients
      6. 1.6. When to Use GET
      7. 1.7. When to Use POST
      8. 1.8. How to Create Resources Using POST
      9. 1.9. When to Use PUT to Create New Resources
      10. 1.10. How to Use POST for Asynchronous Tasks
      11. 1.11. How to Use DELETE for Asynchronous Deletion
      12. 1.12. When to Use Custom HTTP Methods
      13. 1.13. When and How to Use Custom HTTP Headers
    4. 2. Identifying Resources
      1. 2.1. How to Identify Resources from Domain Nouns
      2. 2.2. How to Choose Resource Granularity
      3. 2.3. How to Organize Resources into Collections
      4. 2.4. When to Combine Resources into Composites
      5. 2.5. How to Support Computing/Processing Functions
      6. 2.6. When and How to Use Controllers to Operate on Resources
    5. 3. Designing Representations
      1. 3.1. How to Use Entity Headers to Annotate Representations
      2. 3.2. How to Interpret Entity Headers
      3. 3.3. How to Avoid Character Encoding Mismatch
      4. 3.4. How to Choose a Representation Format and a Media Type
      5. 3.5. How to Design XML Representations
      6. 3.6. How to Design JSON Representations
      7. 3.7. How to Design Representations of Collections
      8. 3.8. How to Keep Collections Homogeneous
      9. 3.9. How to Use Portable Data Formats in Representations
      10. 3.10. When to Use Entity Identifiers
      11. 3.11. How to Encode Binary Data in Representations
      12. 3.12. When and How to Serve HTML Representations
      13. 3.13. How to Return Errors
      14. 3.14. How to Treat Errors in Clients
    6. 4. Designing URIs
      1. 4.1. How to Design URIs
      2. 4.2. How to Use URIs As Opaque Identifiers
      3. 4.3. How to Let Clients Treat URIs As Opaque Identifiers
      4. 4.4. How to Keep URIs Cool
    7. 5. Web Linking
      1. 5.1. How to Use Links in XML Representations
      2. 5.2. How to Use Links in JSON Representations
      3. 5.3. When and How to Use Link Headers
      4. 5.4. How to Assign Link Relation Types
      5. 5.5. How to Use Links to Manage Application Flow
      6. 5.6. How to Deal with Ephemeral URIs
      7. 5.7. When and How to Use URI Templates
      8. 5.8. How to Use Links in Clients
    8. 6. Atom and AtomPub
      1. 6.1. How to Model Resources Using Atom
      2. 6.2. When to Use Atom
      3. 6.3. How to Use AtomPub Service and Category Documents
      4. 6.4. How to Use AtomPub for Feed and Entry Resources
      5. 6.5. How to Use Media Resources
    9. 7. Content Negotiation
      1. 7.1. How to Indicate Client Preferences
      2. 7.2. How to Implement Media Type Negotiation
      3. 7.3. How to Implement Language Negotiation
      4. 7.4. How to Implement Character Encoding Negotiation
      5. 7.5. How to Support Compression
      6. 7.6. When and How to Send the Vary Header
      7. 7.7. How to Handle Negotiation Failures
      8. 7.8. How to Use Agent-Driven Content Negotiation
      9. 7.9. When to Support Server-Driven Negotiation
    10. 8. Queries
      1. 8.1. How to Design URIs for Queries
      2. 8.2. How to Design Query Responses
      3. 8.3. How to Support Query Requests with Large Inputs
      4. 8.4. How to Store Queries
    11. 9. Web Caching
      1. 9.1. How to Set Expiration Caching Headers
      2. 9.2. When to Set Expiration Caching Headers
      3. 9.3. When and How to Use Expiration Headers in Clients
      4. 9.4. How to Support Caching for Composite Resources
      5. 9.5. How to Keep Caches Fresh and Warm
    12. 10. Conditional Requests
      1. 10.1. How to Generate Last-Modified and ETag Headers
      2. 10.2. How to Implement Conditional GET Requests in Servers
      3. 10.3. How to Submit Conditional GET and HEAD Requests from Clients
      4. 10.4. How to Implement Conditional PUT Requests in Servers
      5. 10.5. How to Implement Conditional DELETE Requests in Servers
      6. 10.6. How to Make Unconditional GET Requests from Clients
      7. 10.7. How to Submit Conditional PUT and DELETE Requests from Clients
      8. 10.8. How to Make POST Requests Conditional
      9. 10.9. How to Generate One-Time URIs
    13. 11. Miscellaneous Writes
      1. 11.1. How to Copy a Resource
      2. 11.2. How to Merge Resources
      3. 11.3. How to Move a Resource
      4. 11.4. When to Use WebDAV Methods
      5. 11.5. How to Support Operations Across Servers
      6. 11.6. How to Take Snapshots of Resources
      7. 11.7. How to Undo Resource Updates
      8. 11.8. How to Refine Resources for Partial Updates
      9. 11.9. How to Use the PATCH Method
      10. 11.10. How to Process Similar Resources in Bulk
      11. 11.11. How to Trigger Bulk Operations
      12. 11.12. When to Tunnel Multiple Requests Using POST
      13. 11.13. How to Support Batch Requests
      14. 11.14. How to Support Transactions
    14. 12. Security
      1. 12.1. How to Use Basic Authentication to Authenticate Clients
      2. 12.2. How to Use Digest Authentication to Authenticate Clients
      3. 12.3. How to Use Three-Legged OAuth
      4. 12.4. How to Use Two-Legged OAuth
      5. 12.5. How to Deal with Sensitive Information in URIs
      6. 12.6. How to Maintain the Confidentiality and Integrity of Representations
    15. 13. Extensibility and Versioning
      1. 13.1. How to Maintain URI Compatibility
      2. 13.2. How to Maintain Compatibility of XML and JSON Representations
      3. 13.3. How to Extend Atom
      4. 13.4. How to Maintain Compatibility of Links
      5. 13.5. How to Implement Clients to Support Extensibility
      6. 13.6. When to Version
      7. 13.7. How to Version RESTful Web Services
    16. 14. Enabling Discovery
      1. 14.1. How to Document RESTful Web Services
      2. 14.2. How to Use OPTIONS
    17. A. Additional Reading
      1. Books
      2. References
    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
      2. Other Atom Elements to Consider
    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

Chapter 1. Using the Uniform Interface

HTTP is an application-level protocol that defines operations for transferring representations between clients and servers. In this protocol, methods such as GET, POST, PUT, and DELETE are operations on resources. This protocol eliminates the need for you to invent application-specific operations such as createOrder, getStatus, updateStatus, etc. How much you can benefit from the HTTP infrastructure largely depends on how well you can use HTTP as an application-level protocol. However, a number of techniques including SOAP and some Ajax web frameworks use HTTP as a protocol to transport messages. Such usage makes poor use of HTTP-level infrastructure. This chapter presents the following recipes to highlight various aspects of using HTTP as an application protocol:

Recipe 1.1

Visibility is one of the key characteristics of HTTP. Use this recipe to learn how to maintain visibility.

Recipe 1.2

There are cases when you may need to forgo visibility to meet application needs. Use this recipe to find some scenarios.

Recipe 1.3

Use this recipe to learn the best way to manage state.

Recipe 1.4

Maintaining safety and idempotency helps servers guarantee repeatability for requests. Use this recipe when implementing servers.

Recipe 1.5

Follow this recipe to implement clients for safety and idempotency principles.

Recipe 1.6

Use this recipe to learn when to use GET.

Recipe 1.7

Use this recipe to learn when to use POST.

Recipe 1.8

Use this recipe to learn how to create new resources using the POST method.

Recipe 1.9

You can use either POST or PUT to create new resources. This recipe will discuss when using PUT is better.

Recipe 1.10

Use this recipe to learn how to use the POST method for asynchronous tasks.

Recipe 1.11

Use this recipe to learn how to use the DELETE method for asynchronous deletion of resources.

Recipe 1.12

Use this recipe to learn why custom HTTP methods are not recommended.

Recipe 1.13

Use this recipe to learn when and how to use custom HTTP headers.

1.1. How to Keep Interactions Visible

As an application protocol, HTTP is designed to keep interactions between clients and servers visible to libraries, servers, proxies, caches, and other tools. Visibility is a key characteristic of HTTP. Per Roy Fielding (see Appendix A for references), visibility is the ability of a component to monitor or mediate the interaction between two other components. When a protocol is visible, caches, proxies, firewalls, etc., can monitor and even participate in the protocol.


You want to know what visibility means and what you can do to keep HTTP requests and responses visible.


Once you identify and design resources, use GET to get a representation of a resource, PUT to update a resource, DELETE to delete a resource, and POST to perform a variety of potentially nonidempotent and unsafe operations. Add appropriate HTTP headers to describe requests and responses.


Features like the following depend entirely on keeping requests and responses visible:


Caching responses and automatically invalidating cached responses when resources are modified

Optimistic concurrency control

Detecting concurrent writes and preventing resource changes when such operations are based on stale representations

Content negotiation

Selecting a representation among alternatives available for a given resource

Safety and idempotency

Ensuring that clients can repeat or retry certain HTTP requests

When a web service does not maintain visibility, such features will not work correctly. For instance, when the server’s usage of HTTP breaks optimistic concurrency, you may be forced to invent application-specific concurrency control mechanisms on your own.


Maintaining visibility lets you use existing HTTP software and infrastructure for features that you would otherwise have to build yourself.

HTTP achieves visibility by virtue of the following:

  • HTTP interactions are stateless. Any HTTP intermediary can infer the meaning of any given request and response without correlating them with past or future requests and responses.

  • HTTP uses a uniform interface consisting of OPTIONS, GET, HEAD, POST, PUT, DELETE, and TRACE methods. Each method in this interface operates on one and only one resource. The syntax and the meaning of each method do not change from application to application or from resource to resource. That is why HTTP is known as a uniform interface.

  • HTTP uses a MIME-like envelope format to encode representations. This format maintains a clear separation between headers and the body. Headers are visible, and except for the software that is creating the message and the software that is processing the message, every piece of software in between can treat the body as completely opaque.

Consider an HTTP request to update a resource:

# Request
PUT /movie/gone_with_the_wind HTTP/1.1 1
Host: 2
Content-Type: application/x-www-form-urlencoded

summary=...&rating=5&... 3

# Response
HTTP/1.1 200 OK 4
Content-Type: text/html;charset=UTF-8 5
Content-Length: ...


Request line containing HTTP method, path to the resource, and HTTP version


Representation headers for the request


Representation body for the request


Response status line containing HTTP version, status code, and status message


Representation headers for the response


Representation body for the response

In this example, the request is an HTTP message. The first line in this message describes the protocol and the method used by the client. The next two lines are request headers. By simply looking at these three lines, any piece of software that understands HTTP can decipher not only the intent of the request but also how to parse the body of the message. The same is the case with the response. The first line in the response indicates the version of HTTP, the status code, and a message. The next two lines tell HTTP-aware software how to interpret the message.

For RESTful web services, your key goal must be to maintain visibility to the extent possible. Keeping visibility is simple. Use each HTTP method such that it has the same semantics as specified by HTTP, and add appropriate headers to describe requests and responses.

Another part of maintaining visibility is using appropriate status codes and messages so that proxies, caches, and clients can determine the outcome of a request. A status code is an integer, and the status message is text.

As we will discuss in Recipe 1.2, there are cases where you may need to trade off visibility for other characteristics such as network efficiency, client convenience, and separation of concerns. When you make such trade-offs, carefully analyze the effect on features such as caching, idempotency, and safety.

The best content for your career. Discover unlimited learning on demand for around $1/day.