Muhammad Asad Siddiqi

REST is an acronym for Representational State Transfer. REST can be described as an architectural style (not a standard) of networked systems. This architecture is vastly becoming popular with Web services. The underlying protocol which is used with web services is http and the distributed systems are connected through the web (internet). REST is an alternative architectural style to SOAP (Simple Object Access Protocol) which instantly gained popularity with the advent of web services and is the widely used standard for web services data transfer.  In this essay I would highlight on the working of REST, the implementation style, characteristics, and principles and compare the architecture with SOAP and try to conclude which one might be better and under what circumstances. In the end I would explain how to use REST with web services by designing a dummy web service which follows the REST architectural style.  

So what does Representational State Transfer mean? 

 As we all know Internet is a collection of various resources. All the resources on the internet (including the web services with a published wsdl) can be accessed through a uniform resource locator (URL) e.g. http://www.mywebsite.com/mywebservice.With Web 2.0 in action static websites are loosing visitor’s interest and we see more and more dynamic web applications like forums, interactive blogs, websites which are regularly updated by users. Example of these applications are wikipedia where the user can moderate the content instantly , youtube where users can update their videos and they immediately become available to potentially everywhere the web application could be accessed with a browser and EBAY where there is real time bidding by the users of the web applications. With REST as the underlying protocol is Hyper Text Transfer Protocol (HTTP) the application changes or transfers its state after each http request / response for each requested resource. 

 “So REST can be considered as an architectural style where a web application changes its state constantly and it is named as Representational State Transfer”. 

Roy fielding (A researcher of this architectural style, defined the key characteristics, motivations, benefits and the circumstances where its implementation might be beneficial) explains REST as:  

“Representational State Transfer is intended to evoke an image of how a well-designed Web application behaves: a network of web pages (a virtual state-machine), where the user progresses through an application by selecting links (state transitions), resulting in the next page (representing the next state of the application) being transferred to the user and rendered for their use.”

  The motivation for REST was to capture the characteristics of the Web which made the Web successful. Subsequently these characteristics are being used to guide the evolution of the Web.In the beginning of the essay I emphasized on REST being an architectural style and not a standard. REST is a way in which web services can be configured to deliver data streams or we can say that client accesses a resource on the World Wide Web and is certainly not a standard like HTTP or XML. The concept is much similar to what Web 2.0 is, you want see W3C putting out a specification on the working details on REST. Same is true for the vendors of software development technology, the software giants like Microsoft, sun and other platforms manufacturers won’t come out with a REST development toolkit simply because it’s an architectural style. By architectural style I mean a way of implementing things or we can say that defining a framework using the existing technology and using it in a way which is more efficient and effective for us. Although REST is itself not an industry standard but as it works with the Web and the distributed world of internet it works in parallel with many industry renowned standards. These include HTTP, XML, HTML, URLs and various file formats like gif, jpeg, text/xml, text/html and other MIME types. Many of the services especially the web services that we use as out day to day routine for our usage and software development services are based on REST and we are even not aware that we are using it. This is because REST does not work with minor implementation details it has more to do with the overall integration of the components that make a web application or a web service work. 

So what are some of the key characteristics of REST? 

As we know that the model that http follows a Client Server paradigm (as it works on the internet)  where the client is the consumer or requests a resource identified by a URL and located on the World Wide Web and the server is a web server which has the required resource and delivers it using HTTP. The Client Server paradigm is further classified into a pull or push based implementation Style. REST is essentially a pull-based implementation style of http where the consumer (consuming services, applications e.g. browser) or client pulls various representations (resources). Another Key characteristic that rest follows and is due to the http being the underlying protocol is it’s stateless. As we know that http is a stateless protocol so each request from client to the server in this http pull-based implementation style should contain all the information which is necessary for the server to understand the request. In other words the client cannot take advantage of any information that is stored in the server’s context and has to send the client’s info with every representation transfer. An optimization and a key characteristic that REST utilizes to overcome performance limitations and overheads is CACHING. When the web server responds to any of its clients with the requested resource the responses should have the ability to be marked as either cacheable or non-cacheable depending on the capability of client which might be an application or a service. So if the client if Caching enabled the performance can be optimized as the implementation architecture supports caching. What it means essentially is if the same resource is requested by the client again and again or for instance the same parameter or argument is passed to a method exposed by a web service the client should know what the service will return and it should directly get the desired result without going through the whole request/response process. Another key characteristic of REST is all REST implementation should follow a uniform interface .This means that all the resources located on the web server can be accessed by using a generic interface such as HTTP Get, Post, Put or delete. In a REST based implementation, each resource that is requested from a web server can be identified with a unique URL. This is pretty much how internet works, the critical components here are the Client and Server Applications, HTTP as the request/ response based protocol, and the Domain Name System (DNS) which resolves the host names to IP Addresses to exactly know where the requested resources are physically located. So it is essential to use named resources while implementing REST. Another key characteristic of REST is interconnected resource representations. This essentially means that the representations of the resources are interconnected using URLs, thereby enabling a client to progress from one state to another. REST uses Layered components which imply that intermediaries, such as proxy servers, cache servers, gateways, etc, can be inserted between clients and resources to support performance, security, or in other words using intermediary devices between the client and the server does not restrict the client from accessing the server. Etc  Designing web services using REST: 

What are some of the key design principles that we have to keep in mind while designing web services that makes use of REST? Primarily all the conceptual entities that the designers or developers wish to expose as services need to be identified. The design principle is not only limited to REST but it’s a general rule of thumb for good web service design. As we know, one of the characteristics of REST is using named resources. Recall that resources are named as URLs .REST uses a particular naming convention to access resources on the web server. REST proposes to use nouns as resource name instead of verbs.  

E.g. URL such as http://www.bookstore.com/books/getBook?id=11234 should not be used instead the resource should be named as http://www.bookstore.com/books/11234   REST follows the phenomenon of categorization of resources. The resources should be categorized in terms of whether they can only be accessed and not changed by the client. Such resources are called Read Only Resources. With Read only resources clients can just receive a representation of the resource. In addition to this the clients can add new resources or modify existing ones. REST suggests categorizing the resources based on resource types. If they are read only resources which the client can access but not modify, only HTTP Get should be specified as an access method whereas if the clients can update the resources then HTTP POST, PUT, and/or DELETE can be used. In this context all resources accessible via HTTP GET should not have any side effects. That is, the resource should just return a representation of the resource. Invoking/calling or requesting the resource should not result in modifying the resource in any way.   As from the above description it is evident that REST (Representational State Transfer) follows a state based implementation, it supports how we can drill down further into the application. REST supports navigation by supporting navigational links so the state of the request changes and recorded.   For designing a REST style web service some performance optimizations are provided as the design guidelines. REST proposes not to present the whole data in one single response simultaneously to the user (client). Instead present a portion of the data with the ability to drill down information by providing navigational links so the user can drill down by again requesting a resource identified the navigational link and thus the state of the client application changes.   If a web service is to be designed that uses REST as the architectural model, the format of the response data has to be defined using a standardized schema such as the Data Type Definition (DTD) or W3c schema or Schematron e.t.c For those services that require a POST or PUT to it, also provide a schema to specify the format of the response.   The SOAP and REST comparison:   Having discussed the working of REST, characteristics and principles of a typical application that follows a REST based architecture and knowing that it is a design alternative to SOAP (Simple Object Access Protocol) the question that comes to our mind is when to use REST and when to use SOAP , what is the key factor that answers this question ? What are the benefits of REST over SOAP and vice versa? Although there are plenty of overheads which can be immediately noticed with implementing SOAP, writing a wrapper class that puts a SOAP envelope on every request response that goes to and from the web service on the client side and configuring the service itself to parse those request may sound like a lot of work. But primarily we now have tools to do it; I have worked with Microsoft Visual Studio where if a wsdl file hosted on the internet is given as an input all the wrappers required for the web service and initializing SOAP are generated automatically, same is true for many DELPHI environments. The advantage of using SOAP is “sending complex data structures to the web service”.  Development tools like Visual Studio or Delphi can read the WSDL from the web service and that gives you the "INTELLISENSE" auto completion functionality that can save a lot of coding time. The drawback with SOAP is that there is more overhead in the construction of the method request and with the parsing of the request on the web service end.  When you have a web service that is serving thousands of requests a minute or second, that overheard may not be needed. This is in contrast with REST where simple HTTP Get and PUT commands are used to interact with the web service. You compose a URL for your web method request and the service sends back a response.  The response is usually in XML, but that is dependant on the functionality of the web service. For web services that have relatively simple data types, using REST can provide the functionality that is needed.  You also get the advantage of testing individual method requests from a browser as the method request is basic URL. Another big advantage of using REST over SOAP is by sticking to simple semantics (especially if you limit yourself to GET as much as possible); it scales much better as it can take advantage of all levels of caching between you and the server. REST takes advantage of the existing scaling mechanisms the internet has grown on top of HTTP - something SOAP cannot do.
 The complex data types can still be used with REST by including them as payloads - you just have to manage interpreting it yourself instead of relying on a rich library layer to make it feel like some native type in your program. So if we compare the contrasting architectural styles, REST is the way to go if you are looking for better performance and the web service consists of simple data types where as SOAP would be better if the client application has to be developed fairly quickly and Complex data structures are to be used.   A REST example – An Online Library Catalogue exposing library data as a service ( A self created dummy service to demonstrate REST) :   Here I would describe the whole process of how REST works and some of the common practices that are followed by developing a simple Library Catalogue Service which would define a couple methods of displaying a list of books and listing a particular book’s details. The functionality that is exposed by the service is:   Generating a list of books   Generating details of a particular book  

 

Generating a list of books:

The web service presents a URL to a “Book listing” resource. For example, a client would use this URL to get the parts list:

http://www.books-online.com/books

The client does not know anything about how the listing is generated by the service. All the client knows is that if he/she submits the above URL then a document containing the list of books is returned. Since the implementation is transparent to clients, the Book’s catalogue is free to modify the underlying implementation of this resource without impacting clients. This follows two major principles or concepts of Software Design, loose coupling and encapsulation.Here’s the document that the client receives whenever the above URL is accessed:

<?xml version="1.0"?>
 <p: books xmlns:p=http://www.books-online.com xmlns:xlink="http://www.w3.org/1999/xlink">
 <Book id="00001" xlink:href="http://www.books-online.com/books/00001" mce_href="http://www.books-online.com/books/00001"/>
 <Book id="00002" xlink:href="http://www.books-online.com/books/00002" mce_href="http://www.books-online.com/books/00002"/>
 <Book id="00003" xlink:href="http://www.books-online.com/books/00003" mce_href="http://www.books-online.com/books/00003"/>
 <Book id="00004" xlink:href="http://www.books-online.com/books/00004" mce_href="http://www.books-online.com/books/00004"/>
 </p: books>    Note that the parts list has links to get detailed info about each book. This is a key feature of REST. The client transfers from one state to the next by examining and choosing from among the alternative URLs in the response document thus resulting in a change of State which REST is all about.   Generating details for a particular book: Any book’s details can be generated by accessing the URL associated with the book’s detail (as presented by the xml in the response above). Again the client receives and XML document which can be parsed for the book’s details.

http://www.books-online.com/books/00001  

Here’s the document that the client receives:  

<? Xml version="1.0"?>
<p: Book xmlns:p="http://www.books-online.com"            xmlns:xlink="http://www.w3.org/1999/xlink">
<BookID>00001</BookID>
 <Title>SOA Concepts, Design and Technology</Title>
 <Description>This book is about Services Oriented Architecture</Description>
 <Author>Thomas Erl</Author>
 <Number of Copies>2</Number of Copies>
<Section>Computer Books</Section>
</p: Book>