REST for Scott
At the thanksgiving dinner of a friend from work I tried to explain REST-ful applications – and I think I failed miserably. Even though there are plenty of good introductions out there I felt I needed to organize my thoughts a bit. Having some spare time on the train on the way home I made a second, more structured attempt in the form of this blog post.
Imagine you are a web developer and is asked by a friend with a travel agency to help out create a web site for his company. Among the services on the site is a small web application for searching for hotels recommended by the agency. These hotels have been carefully vetted for the agency’s customer segment and useful hotel information is stored in a database.
Let us assume the web application manages the namespace under the URL
One way to construct the application is by storing e.g. navigation state in a server side session or as post parameters in the HTTP requests. Or maybe use an AJAX user interface where parts of the page is updated asynchronously in the background. These approaches are, however, incompatible with the basic requirement of you friend the the travel agent, who frequently copies the URL of a particular hotel and sends it per email to potential customers. He would also like his customers and all other users of the web site to be able to send URLs, create bookmarks etc. Only by creating stable, re-usable URL’s is this easily accomplished. Thus you decide on a basic categorization scheme where each hotel is listed under
Where is the two letter ISO code for the country, the city name in english using only ascii characters and is a unique name of the hotel (unique at least within the country). By typing in a URL like
… in a web browser you would end up with the HTML page describing the Grand Hotel in Stockholm, Sweden.
Your friend is very ambitious but would like to start out small. Uptime is of course important but not critical and you offer to host the site on your server at your place for a minor fee per month. (This would help pay the electricity and internet connection bills.)
Now, your friend has a business partner who organizes conferences in different countries around the globe. The business partner would like to link to specific hotels on your site, hotels your friend has arranged special deals and have pre-booked a number of rooms for. Since you are using stable and predictable URLs this is no big deal, for any particular conference the business partner can easily add the reference on a web page, add them in emails sent out to the participants and even in printed hard copy.
As the partnership between your friend and his business partner deepens, the business partner would like tighter integration between the two web sites. In particular he would like to create a mashup application where each conference has a map with all the hotels printed at the correct geographic location. Since your friend has stored the exact geo location of each hotel in his database it should not be too difficult to achieve.
Being well versed in XML and enterprise standards you now ponder a bit on web services. You could of course create a web service with a method which would accept a list of hotel identifiers and return a list coordinates… After some deliberation you come to the conclusion it would be easiest to use the URLs as identifiers. They are unambiguous and you do not have to expose the primary keys of the database to the internet and there is no need to create new unique external identifiers. On top of that adding the identifiers to the mashup will be easy since the URLs are already used on the conference web page.
Thinking a bit further you realize that in the future there potentially is more information which could be useful, not just the coordinates. Right now you do not know exactly what information that would be, but if you return a list of XML documents containing basic information on each hotel and with geo-coordinates, you can always expend the XML document format to include additional information at a later stage. At least as long you are careful to keep the format backwards compatible. This you do by not changing the meaning and syntax of the existing XML and make sure the XML elements have the same position relative to the root element (i.e. that the XPath for the elements is stable).
Finally, you realize that instead of taking the pain of having to create a web service with SOAP, WSDLs etc you decide that each hotel URL should return the corresponding XML if the client asks to get the hotel information in XML format instead of HTML. This can easily be accomplished by using the standard HTTP content negotiation, i.e. the client sends a list of desired formats and the server responds with a document in one of the formats if it can.
The changes to the existing application are relatively minor, you only need to implement the content negotiation feature and in addition to render HTML you will need a mechanism to render XML. (In Java, using servlets, servlet filters and a templateing mechanism sounds like a good approach.)
The result is a huge success. Business is booming for your friend and traffic to your server is increasing at an alarming rate. You are sure that any minute your ISP will knock on the door telling you you are violating the fair use clause of your contract. In addition, uptime is becoming more of a concern. If not for the load so at least for redundancy you need two servers. You decide to move the web site to a hosting facility. Since state is not kept in a server side session you realize that clustering will be trivial. Each request is independent of the previous meaning it can land on either server without complication. This also means adding more servers to handle a larger load will be a breeze.
Some time later your friend has found an additional business partner – this guy for some reason wants to create an AJAX client which uses the hotel information. The AJAX guys, programming in client side Java script, do not really like XML and prefer something called JSON. Would it be possible to add JSON support? In addition it would be nice if you could create a downloadable PDF for each hotel…
Having the infrastructure already set up, all is needed is to add two new rendering templates, one for JSON and one for PDF’s and add the two new formats to the lists served by the server.
–
*The above scenario describes using REST – REpresentational State Transfer – for building a web application. The text strives to illustrate the fundamental REST-ful principle of decoupling the reference of an object from its actual representation. It can also be said that in REST you take a resource or document oriented approach to software development, i.e. development is data-driven. This is opposed to service orientation with an RPC style of defining interfaces where focus is not on the data but rather on what you do with data; the focus is on the verbs instead of the nouns. In REST the actions are a well defined minimum like the four most well known HTTP verbs: GET, POST, PUT and DELETE. Above, only the implied use of GET is shown.
*
Using REST principles is not constrained to web applications. It has been suggested that REST should be used instead of SOAP based web services in a SOA architecture, thus imbuing some of the webs scalability and robustness in an Enterprise Integraion scenario. Gartner has termed it WOA for Web Oriented Architecture. WOA can be seen as a more constrained version of SOA.
It has even been suggested that REST is useful within applications. How this can be done is described in four articles on The Server Side. Beware though, although well written they end up being a plug for NetKernel, a REST-ful application server built on something they call ROC – Resource Oriented Computing. I would say the jury is still out on question whether using REST internally in an application is a good alternative or not.
References
Wikipedia has a well written article on REST:
http://en.wikipedia.org/wiki/REST
Web Oriented Architecture
*http://hinchcliffe.org/archive/2008/02/27/16617.aspx
*
*The Server Side, A Restful Core:
*
http://www.theserverside.com/tt/articles/article.tss?l=ARESTfulCorePart1
http://www.theserverside.com/tt/articles/article.tss?l=ARESTfulCorePart2
http://www.theserverside.com/tt/articles/article.tss?l=ARESTfulCorePart3
http://www.theserverside.com/tt/articles/article.tss?l=ARESTfulCorePart4