Home arrow Web Services arrow 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
(Page 1 of 4 )

Deciding Between Representations

If a server provides multiple representations of a resource, how does it figure out which one the client is asking for? For instance, a press release might be put out in both English and Spanish. Which one does a given client want?

There are a number of ways to figure this out within the constraints of REST. The simplest, and the one I recommend for the Resource-Oriented Architecture, is to give a distinct URI to each representation of a resource. http://www.example.com/releases/104.en could designate the English representation of the press release, and http:// www.example.com/releases/104.es could designate the Spanish representation.

I recommend this technique for ROA applications because it means the URI contains all information neccessary for the server to fulfill the request. The disadvantage, as whenever you expose multiple URIs for the same resource, is dilution: people who talk about the press release in different languages appear to be talking about different things. You can mitigate this problem somewhat by exposing the URI http:// www.example.com/releases/104 to mean the release as a Platonic form, independent of any language.

The alternative way is called content negotiation. In this scenario the only exposed URI is the Platonic form URI, http://www.example.com/releases/104. When a client makes a request for that URI, it provides special HTTP request headers that signal what kind of representations the client is willing to accept.

Your web browser has a setting for language preferences: which languages youíd prefer to get web pages in. The browser submits this information with every HTTP request, in the Accept-Language header. The server usually ignores this information because most web pages are available in only one language. But it fits with what weíre trying to do here: expose different-language representations of the same resource. When a client requests http://www.example.com/releases/104, the server can decide whether to serve the English or the Spanish representation based on the clientís Accept-Language header.

The Google search engine is a good place to try this out. You can get your search results in almost any language by changing your browser language settings, or by manipulating the hl query variable in the URI (for instance, hl=tr for Turkish). The search engine supports both content negotiation and different URIs for different representations.

A client can also set the Accept header to specify which file format it prefers for representations. A client can say it prefers XHTML to HTML, or SVG to any other graphics format.

The server is allowed to use any of this request metadata when deciding which representation to send. Other types of request metadata include payment information, authentication credentials, the time of the request, caching directives, and even the IP address of the client. All of these might make a difference in the serverís decision of what data to include in the representation, which language and which format to use, and even whether to send a representation at all or to deny access.

Itís RESTful to keep this information in the HTTP headers, and itís RESTful to put it in the URI. I recommend keeping as much of this information as possible in the URI, and as little as possible in request metadata. I think URIs are more useful than metadata. URIs get passed around from person to person, and from program to program. The request metadata almost always gets lost in transition.

Hereís a simple example of this dilemma: the W3C HTML validator, a web service available at http://validator.w3.org/. Hereís a URI to a resource on the W3Cís site, a validation report on the English version of my hypothetical press release: http:// validator.w3.org/check?uri=http%3A%2F%2Fwww.example.com%2Freleases%2F104.en.

Hereís another resource: a validation report on the Spanish version of the press release:

Every URI in your web space becomes a resource in the W3Cís web application, whether or not it designates a distinct resource on your site. If your press release has a separate URI for each representation, you can get two resources from the W3C: validation reports for the English and the Spanish versions of the press release.

But if you only expose the Platonic form URI, and serve both representations from that URI, you can only get one resource from the W3C. That would be a validation report

Figure 4-3. Closeup on a page of Google search results

for the default version of the press release (probably the English one). Youíve got no way of knowing whether or not the Spanish representation contains HTML formatting errors. If the server doesnít expose the Spanish press release as its own URI, thereís no corresponding resource available on the W3C site. This doesnít mean you canít expose that Platonic form URI: just that it shouldnít be the only URI you use.

Unlike humans, computer programs are very bad at dealing with representations they didnít expect. I think an automated web client should be as explicit as possible about the representation it wants. This almost always means specifying a representation in the URL.

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-2019 by Developer Shed. All rights reserved. DS Cluster - Follow our Sitemap
Popular Web Development Topics
All Web Development Tutorials