The Resource-Oriented Architecture in Action
(Page 1 of 4 )
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.
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:
http://validator.w3.org/check?uri=http%3A%2F%2Fwww.example.com%2Freleases%2F104.es.
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.
Next: Links and Connectedness >>
More Web Services Articles
More By O'Reilly Media
|
 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). Check it out today at your favorite bookstore. Buy this book now.
|
|
