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

http://qualitytravel.com/hotel

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

http://qualitytravel.com/hotel///

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

http://qualitytravel.com/hotel/se/stockholm/grand-hotel

… 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

In a famous post from January this year (which I missed) Ann Thomas Manes declares SOA dead. She is a Reasearch Director within the Burton Group, has worked with SOA in the Burton Group and elsewhere, and is a co-author of the WS-* specifications.

The post has sparked fierce defense from vendors like Oracle. During the half day SOA Architect forum in Geneva this Tuesday, Oracle spent the first seminar repeating that “SOA is not dead” like a mantra, I guess in order to reinforce the message. It seemed to be one of the mayor points they wanted to get across.

Excerpt from Ann Thomas Manes post SOA is Dead; Long Live Services

Successful SOA (i.e., application re-architecture) requires disruption to the status quo. SOA is not simply a matter of deploying new technology and building service interfaces to existing applications; it requires redesign of the application portfolio. And it requires a massive shift in the way IT operates. The small select group of organizations that has seen spectacular gains from SOA did so by treating it as an agent of transformation. In each of these success stories, SOA was just one aspect of the transformation effort. And here’s the secret to success: SOA needs to be part of something bigger. If it isn’t, then you need to ask yourself why you’ve been doing it.

The latest shiny new technology will not make things better. Incremental integration projects will not lead to significantly reduced costs and increased agility. If you want spectacular gains, then you need to make a spectacular commitment to change. Like Bechtel. It’s interesting that the Bechtel story doesn’t even use the term “SOA”—it just talks about services.

And that’s where we need to concentrate from this point forward: Services.

This falls in line with my understanding that SOA without BPR/BPM/Transformation really does not amount to much. You need the entire organization to support a process and service view on business and IT in order to see real benefit.

In another post SOA is Dead? It’s About Time by Kurt Cagle acknowledges Ann Thomas Manes view but complements the picture with adding that

Perhaps my biggest reservation about SOA had to be the fact that, at the end of the day, it was still an RPC model that concentrated primarily on calling APIs that differed from one provider to the next. The result of this thinking is the sea of APIs, where there are now tens of thousands of APIs, each of which doing things a little (or in some cases, a lot) differently from one another, with very little cohesion, and with little thought to the semantic complexity that comes when you have that many microlanguages all competing for programmer attention.

Purists may argue that over time the SOA model (especially the SOAP/WSDL model) had been moving towards a more messaging-oriented architecture, but I’d counter that all that a messaging queue does is to decouple the receipt of the message from the response – if the message processor invokes a service, it is still an RPC, especially when transactions are involved.

This is one of the reasons that I think that resource oriented services – RESTful services – are beginning to gain real traction even as the big-box SOA projects are falling to the accountant’s axe. The publish/subscribe model in which what you’re publishing are not blogs but data documents (think XBRL or HL7) performs the same type of decoupling that message-oriented SOA did, but completely abstracts the intent from the process of communication.

This is consistent with my view that SOA, which if done correctly, should be document or data driven and should rely on messaging. As an alternative to an ESB used mainly for RPC over SOAP Web Services, I think that an REST-ful approach should be seriously considered when attempting SOA. Some thinkers at Gartner have started talking about a WOA – Web Oriented Architecture – as further constrained subset of the SOA approach based on REST principles.

I believe the change will be heavily resisted by companies like Oracle and IBM since there is less money to be made on the simpler and less tool/platform-intensive REST-ful approach to enterprise computing. Also they all have invested heavily in the WS-* and RPC-style SOA corner and thus are reluctant to change. But change will come sooner or later and the ongoing economical crisis will be a strong driver.