Home arrow Web Services arrow Page 3 - The Resource-Oriented Architecture in Action

The Resource-Oriented Architecture in Action

In this third part of a four-part article series on the resource-oriented architecture, you will learn how servers figure out which resource a client wants, the four basic things you can do to a resource online, and more. This article is excerpted from chapter four of the book RESTful Web Services, written by Leonard Richardson and Sam Ruby (O'Reilly, 2008; ISBN: 0596529260). Copyright © 2008 O'Reilly Media, Inc. All rights reserved. Used with permission from the publisher. Available from booksellers or direct from O'Reilly Media.

Author Info:
By: O'Reilly Media
Rating: 5 stars5 stars5 stars5 stars5 stars / 7
February 12, 2009
  1. · The Resource-Oriented Architecture in Action
  2. · Links and Connectedness
  3. · The Uniform Interface
  4. · Creating subordinate resources

print this article

The Resource-Oriented Architecture in Action - The Uniform Interface
(Page 3 of 4 )

All across the Web, there are only a few basic things you can do to a resource. HTTP provides four basic methods for the four most common operations:

  1. Retrieve a representation of a resource: HTTP GET

  2. Create a new resource: HTTP PUT to a new URI, or HTTP POST to an existing URI (see the ďPOST Ē section below)
  3. Modify an existing resource: HTTP PUT to an existing URI
  4. Delete an existing resource: HTTP DELETE

Iíll explain how these four are used to represent just about any operation you can think of. Iíll also cover two HTTP methods for two less common operations: HEAD and OPTIONS.


These three should be familiar to you from the S3 example in Chapter 3. To fetch or delete a resource, the client just sends a GET or DELETE request to its URI. In the case of a GET request, the server sends back a representation in the response entity-body. For a DELETE request, the response entity-body may contain a status message, or nothing at all.

To create or modify a resource, the client sends a PUT request that usually includes an entity-body. The entity-body contains the clientís proposed new representation of the resource. What data this is, and what format itís in, depends on the service. Whatever it looks like, this is the point at which application state moves onto the server and becomes resource state.

Again, think of the S3 service, where there are two kinds of resources you can create: buckets and objects. To create an object, you send a PUT request to its URI and include the objectís content in the entity-body of your request. You do the same thing to modify an object: the new content overwrites any old content.

Creating a bucket is a little different because you donít have to specify an entity-body in the PUT request. A bucket has no resource state except for its name, and the name is part of the URI. (This is not quite true. The objects in a bucket are also elements of that bucketís resource state: after all, theyíre listed when you GET a bucketís representation. But every S3 object is a resource of its own, so thereís no need to manipulate an object through its bucket. Every object exposes the uniform interface and you can manipulate it separately.) Specify the bucketís URI and youíve specified its representation. PUT requests for most resources do include an entity-body containing a representation, but as you can see itís not a requirement.


There are three other HTTP methods I consider part of the uniform interface. Two of them are simple utility methods, so Iíll cover them first.

  1. Retrieve a metadata-only representation: HTTP HEAD
  2. Check which HTTP methods a particular resource supports: HTTP OPTIONS

saw the HEAD method exposed by the S3 servicesís resources in Chapter 3. An S3 client uses HEAD to fetch metadata about a resource without downloading the possibly enormous entity-body. Thatís what HEAD is for. A client can use HEAD to check whether a resource exists, or find out other information about the resource, without fetching its entire representation. HEAD gives you exactly what a GET request would give you, but without the entity-body.

There are two standard HTTP methods I donít cover in this book: TRACE and CONNECT. TRACE is used to debug proxies, and CONNECT is used to forward some other protocol through an HTTP proxy.

The OPTIONS method lets the client discover what itís allowed to do to a resource. The response to an OPTIONS request contains the HTTP Allow header, which lays out the subset of the uniform interface this resource supports. Hereís a sample Allow header:

  Allow: GET, HEAD

That particular header means the client can expect the server to act reasonably to a GET or HEAD request for this resource, but that the resource doesnít support any other HTTP methods. Effectively, this resource is read-only.

The headers the client sends in the request may affect the Allow header the server sends in response. For instance, if you send a proper Authorization header along with an OPTIONS request, you may find that youíre allowed to make GET, HEAD, PUT, and DELETE requests against a particular URI. If you send the same OPTIONS request but omit the Authorization header, you may find that youíre only allowed to make GET and HEAD requests. The OPTIONS method lets the client do simple access control checks.

In theory, the server can send additional information in response to an OPTIONS request, and the client can send OPTIONS requests that ask very specific questions about the serverís capabilities. Very nice, except there are no accepted standards for what a client might ask in an OPTIONS request. Apart from the Allow header there are no accepted standards for what a server might send in response. Most web servers and frameworks feature very poor support for OPTIONS. So far, OPTIONS is a promising idea that nobody uses.


Now we come to that most misunderstood of HTTP methods: POST. This method essentially has two purposes: one that fits in with the constraints of REST, and one that goes outside REST and introduces an element of the RPC style. In complex cases like this itís best to go back to the original text. Hereís what RFC 2616, the HTTP standard, says about POST (this is from section 9.5):

POST is designed to allow a uniform method to cover the following functions:

  1. Annotation of existing resources;
  2. Posting a message to a bulletin board, newsgroup, mailing list, or similar group of articles;
  3. Providing a block of data, such as the result of submitting a form, to a data-handling process;
  4. Extending a database through an append operation.

The actual function performed by the POST method is determined by the server and is usually dependent on the Request-URI. The posted entity is subordinate to that URI in the same way that a file is subordinate to a directory containing it, a news article is subordinate to a newsgroup to which it is posted, or a record is subordinate to a database.

What does this mean in the context of REST and the ROA?

blog comments powered by Disqus

- Dealing with Loose Coupling in a Service-Ori...
- Loose Coupling in a Service-Oriented Archite...
- Safety, Idempotence, and the Resource-Orient...
- The Resource-Oriented Architecture in Action
- Features of the Resource-Oriented Architectu...
- The Resource-Oriented Architecture
- Getting Started with Flex
- Automated Billing and Faxing for the Web
- An Introduction to Web Services
- The Foundations of Web Services: From Novice...
- Web Services Reengineering: Finishing Touches
- Fault Handling with Web Services
- Flow and Web Services
- Process Lifecycles and Web Services
- Business Processes and Web Services

Watch our Tech Videos 
Dev Articles Forums 
 RSS  Articles
 RSS  Forums
 RSS  All Feeds
Write For Us 
Weekly Newsletter
Developer Updates  
Free Website Content 
Contact Us 
Site Map 
Privacy Policy 

Developer Shed Affiliates


© 2003-2018 by Developer Shed. All rights reserved. DS Cluster - Follow our Sitemap
Popular Web Development Topics
All Web Development Tutorials