How I explained REST to myself

My recent visit to the passport office to renew my passport was a complicated and messy affair. Back at the office, mulling over the whole experience, I realized that my interaction with the passport office is a perfect example of a REST based service and how Roy Fielding would describe a true REST architecture.

Let me talk about my experience briefly before I get to how I relate it to core REST principles.

Looking around in the main hall as I entered the passport office at the appointed time, I found a window with a sign that displayed “for online appointments”. I presented my application form and all documents to the officer at the window. After going thru my papers, the officer told me to go to Window6 in Hall 2 as he handed me my papers back. He was probably too busy to answer to my queries and gave me a look that clearly meant – just do as told.

So I went to Window6 in Hall2, stood in a short queue, and when my turn came, gave my papers to the officer at the window. After checking my documents again and making some entries, the officer handed the documents back to me and I was told to go back to the window I came from. By this time, I had realized that it is in my best interest to do what is told and not worry too much about figuring out the process.

Back at the the window where I started from, I again forwarded my documents, checked and stamped many times now, to the window officer. This time I was asked to make the fee payment. After making the payment, I was handed back a receipt and mercifully told that the process is over.

At the core of REST architectural style, is something called – HATEOAS – “Hypermedia as the engine of application state”. A user can transition to next state using only Hypertext and links provided in the server response. Based on the current application state, server determines what actions can be performed by the user to transition to future application state(s). An important advantage of this architectural style is that client can easily adapt to changes in server responses since the path taken by the user thru the application is strictly based on server responses.

In my context of interaction with the passport officers, what I needed to do next was determined by the response I got from the officer at the window I visited first. Based on my information, I was told which window I need to go to next. Following instructions provided by the officers, I moved from one stage to next in the application process. This is not different from a REST based server that guides its clients on possible next states thru hypertexts and links provided in the representation of the resource(s) accessed.

A true REST architecture makes it mandatory for the client to discover all future actions dynamically using the hypermedia links provided in the server response. The client then needs to know only the entry point URL into the application and from there on discover future actions from the server responses. In my case, that entry point was a window with a sign board stating “For Online Appointments”. Once I accessed that, I had to discover all future actions thru instructions received from the passport officers.

“Media type ” is another important concept in REST architectural style that makes it possible for REST API to be the true driver of the application state. Media type standardizes out-of-band information that further guides the interaction between the client and the server. For ex., Media type such as “text/html” defines the rendering model and the browser behavior for HTML markup elements. In my example, I would characterize media-type to be “Go-to-the-next-window-as-told”. This clearly defined my behavior around the response(s) that I received from the officers.

Having the system in control of all activities does provide lot of flexibility and strength to the whole process, even though it may seem chaotic from a user perspective. It is a discovery process just as a true REST application server would want its clients to do.