Thinking In Rest - Part 2
So last time I covered the concept of resources (if you haven't read it yet, you should check that out here first) and the idea that when browsing the web you aren't looking at "pages" but instead you are looking at resources that happen to be formatted as pages. As it turns out, an HTML page is a pretty convenient format for a resource when a human is accessing it. Unfortunately, HTML is pretty poor for machine consumption - so how do we provide resources to client programs?
Representations
As is talked about in the very excellent book RESTful Web Services (OReilly) your resources can have more than one representation. A representation is basically a different way of delivering the same information - kind of like Tylenol. If you think about Tylenol you can get it in many forms: Gelcaps, Pills, Liquid, and Chewables. No matter what you are still getting Tylenol, it's just up to you to select the representation that is easiest for you to consume.
Obviously the most typical representation on the web is HTML. RESTful services however are most commonly found using XML, JSON, or both. The thing to understand is that it really doesn't matter. You could use any representation you like and it would still be REST. Just be sure to choose representations that your clients are likely going to be able to consume (imagine how well a new Tylenol delivered in convenient 30 Ton block form would go over).
Give Them What They Want
Many of us web surfers take certain parts of the web experience for granted. Such as getting back some HTML when we ask for a web page. It just seems natural that this would happen automatically; but it doesn't. Behind the scenes your web browser is telling the server what it wants and the server is paying attention. Here's an example of what I'm talking about. When I visit my weblog, I instruct my browser to go to: http://weblogs.asp.net/FreedomDumlao. My browser responds by doing the following:
GET /freedomdumlao/ HTTP/1.1 Accept: text/html,application/xhtml+xml,application/xml Accept-Language: en-us
As you can see - the browser actually tells the server that it will accept HTML, XHTML, or XML. It even tells the server what language it will accept content in! It is then up to you, the service provider to attempt to comply with the request. Likewise, if you can't do what the client wants, you should tell them so.
Using the Accept header is a perfectly reasonable way of having your clients tell you what they want - but not always practical. Another common method is for the client to specify what they want by appending an extension onto the end of the URI. I first saw this practice used by the folks over in the Ruby on Rails camp, and it is also mentioned as a best practice in RESTful Web Services (OReilly). Using this method, the client would request one of the following URLs:
http://fakehost.com/posts.html http://fakehost.com/posts.xml http://fakehost.com/posts.json
No matter which one they call, they'll get the same data, with the representation that is implied by the extension. if the extension is not practical, you might consider adding the desired representation to the url path instead:
http://fakehost.com/html/posts http://fakehost.com/xml/posts http://fakehost.com/json/posts
You might think that this is inconsequential for the service you plan on building - because you your service will only have 1 representation. This is fine - however your client should still indicate in some way what it expects.
Making Things Happen
So we understand now that REST is about resources and resources can have any representation that we want them to. In the next article I'll discuss how we can create, update, and delete our RESTful resources.