Infosys Microsoft Alliance and Solutions blog

« Part 1: Art of Presentation | Main | Am on Windows 7 RTM »

How i explained REST to a SOAP pro

Through this dialogue based interaction I (Sudhanshu) Demystify REST based Architecture to a SOAP pro (Atul). You can additionally refer to slides and code samples posted on the following blog. Wherever i have referred to demos, the corresponding code samples are at following site
Let’s enjoy this ride together.

Atul: Let’s look at how distributed architectures evolved.

Distributed Architecture Evolution (Slide 3)

It all started with monolithic mainframe application with calls restricted to machine boundary. Enterprise Applications grew in complexity and needed more and more calls to be made across machine boundary, which was made possible with DCOM CORBA architectural styles.
Further on, there was a need to connect across enterprise boundaries to other domains, partner networks. The complexity and volume of calls across enterprise boundaries continued to grow rapidly and needed more pervasive, secured protocol to communicate with other applications and services over web. SOAP based services helped address these needs.

SOAP (Slide 4)
SOAP is transport neutral and supports multiple transports like Http, ftp, JMS, SMTP, TCP, MQ, etc. and is platform agnostic

They implement WS* specifications like WS-Atomic Transaction, WS-Security, WS-Interoperability, WS-Reliability, etc and hence are highly secure, reliable, and transactional.

To support adoption of SOAP based services, lot of vendors have used the specifications to implement technology and tools, like Microsoft SOAP toolkit, SOAP with Attachments API for Java, and IBM’s SOAP4J.

Sudhanshu: Atul, Atul, I understand that you are SOAP guy, but I would like to bring out another perspective on SOAP

SOAP has some Limitations (Slide 5)
I agree, it supports multiple protocols and it builds on this protocol stack by implementing WS* specifications. But this makes the stack complex. It completely hides the core underlying protocol.

The communicating parties need to agree on a specific SOAP contract. Hence you cannot start consuming the services without complying with the contract and this affects the interoperability.
As soap is rich and supports multiple standards like WSDL, WS*, XML , etc.., it increases the message size. This has impact on the validation, parsing and translation time and hence on application performance.

There is high entry barrier with SOAP as working with it requires one to follow the specifications, which requires investment in technology, tools and skills.

Atul: Hmm. Sudhanshu, what you say makes sense. But then if SOAP has these issues, what is the alternative?

SudhanshuAtul. Let me introduce you to REST.

Introducing REST (Slide 6)
REST stands for Representational State Transfer, and is an Architecture style for building services on World Wide Web (WWW) and was first introduced by Dr. Roy Fielding through his dissertation in year 2000.
REST based services relies on already built web infrastructure.

Atul:  That’s interesting. Sudhanshu, can you elaborate on your last point a bit more.

Sudhanshu:  Sure. 

REST leverages the already built web infrastructure like Web which is mainly built on http Programming model. REST is built completely on http and leverages all the attributes of http like Uri, http methods, caching, chunking, http error codes and so on.

Unlike SOAP, which only uses POST operation, REST uses all http operations like GET, POST, PUT, and DELETE. REST services are easily discoverable through Web URLs as against the Service Discovery in SOAP. It uses http error codes to communicate response messages to the user. All this together makes REST a good citizen of Web.

Let’s take a look at how typical Http call takes place.

Typical Http call (Slide 7)

A user initiates a request from his or her browser. The web server receives this URL, locates the resource requested and returns it to the client browser along with the status message. The resource is transferred over wire in the format specified.

Atul: a few aspects that I notice from this interaction. There is a specific URI, there is a GET operation, and there is a specific response with appropriate code.

Sudhanshu: You are right on target Atul. Also note that this entire operation is stateless. All this translates in to REST design principles

REST Design principle -1 (Slide 8)
Design principle 1 is - everything that needs to be identified on Web should be treated as a resource. Document, Order, Product, Customer, are all examples of valid resources. For example – The following url identifies order as a resource with order ID 1234. SOAP, it is more of operation/verb oriented design approach, while in case of REST it is resource oriented, resources are treated as Nouns.

REST Design principle-2 (Slide 9)

Design principle 2 is - Use standard http methods to operate on resources.
GET is for getting a resource and possibly cache it
POST is for Inserting or appending to a resource
PUT for updating a resource
DELETE is for deleting a resource

Atul: Sudhanshu, I understand SOAP, but am not able to relate to all this. Can you show how all these translate into URIs? 

Mapping SOAP methods to REST (Slide 10)

Here is the mapping of SOAP service operations to REST operations. For Insert and Update one will have to pass the xml as depicted here.

All URLS need to be unique and you will see that GET has TASKS/taskId while DELETE has TASK/taskID.

Atul: but if we go with the idea of unique URLs for each resource access, isn’t that like making too many chatty calls over the wire?

SudhanshuAtul that is a great question and REST’s third design principal is really about this aspect.

REST Design principle 3 (Slide 11)

Web is beautiful because we can navigate from one page to another page and there are links to do that. Imagine if there were no links? Web wouldn’t have been this beautiful. The design principle is - Connect lower order resources using links to form a higher order resource.  
The below example illustrates an Order with an Order id of 1234, having product with code 455 for customer id 20084 with billing amount as 15000

Let me quickly take you through principle 4 and 5.
REST Design principle 4 and 5 (Slide 12)

Design principle 4 - The resource should be presented to user or client in multiple formats as the client desires. The formats can be anything like Document, PDF, XML, JPG, JSON, Binary, HTML, ATOM, etc. and finally the fifth principle states that the interaction with resource should be stateless
Atul: Wow! SOAP has specifications and REST has principles.

haa haaa ! you are right Atul, but unlike specifications, principles are flexible and allows one to create high rest or low rest type architectures.

Hi-Rest Low-REST (Slide 13)

Hi-Rest applications strictly follows all the REST design principles we discussed so far. Low-REST application follows design principles but also look for practicality of the same and hence is called Pragmatist approach.
e.g. A Low REST application can make Ajax or POX(Plain Old XML) calls, can have URIs with query string params, can use only POST and invoke PUT and DELETE through it.
The above URL has .svc extension as part of it and hence can be called treated as LOW-REST. To translate this into Hi-REST one can use URL- Rewrite module from IIS 7 and translate this to more user friendly URL like the one as

Atul: OK! But with SOAP I have in-built .net framework support to implement SOAP services. What about REST?

Sudhanshu: There is good framework support for REST.
Framework support for REST
(Slide 14)

Built in support for REST exists in .Net 3.5 onwards through namespace System.ServiceModel.Web
It provides WCF specific APIs and behaviors, importantly it also provides WebHttpBinding to abstract Http protocol behavior through WebHttp, which helps in development of RESTful services. It does not use SOAP envelops. It supports http and https transports.
UriTemplate, WebGet, WebInvoke are the Web attributes.
UriTemplate binds WCF operation to unique URI.

WebGet and WebInvoke helps in mapping http GET/POST/PUT/DELETE to a resource. It also helps in defining the request and response formats, the formats can be XML, or JSON.
With this background, let me also quickly show you how all this stack up to create the architecture . 

REST architecture (Slide 15)


We have .Net framework as a lowest layer in stack. Apart from providing standard XML serialization and other capabilities, it provides System.ServiceModel.Web assembly for exposing REST based WCF Services.

IIS can be used to host the REST Services. Browser sends the request to IIS, IIS locates resource and sends the response to the client in desired format with appropriate response code.
IIS can be used to implement additional security like limit number of calls to specific URI. Lot of vendors allows only limited (say 100) calls from specific user to specific URI per day, this helps in avoiding any attacks on the site. Also you can secure pages using https, implement client certificates and so on.

If you don’t want to use IIS, REST Starter kit also provides a service host to host the services. ADO.Net data Services can be used to expose Database entities and data as REST services.

All theory and no play, makes Jack a dull boy.

haa haa.  I get what you are hinting towards. So let me quickly show you some working demos.
Demo 1
-Task Management REST Service Demo (RESTTaskManagementService project) (Slide 16 )
Let’s take a look at the Task Management REST service demo. This demo demonstrates various task management related operations like Create task, Update Task (AssignTask), Delete Task, Get all tasks.
.cs -
                The task has id, title, description, owner and create date. This is captured in the dataContract.

IManageTask.cs - Let’s take a look at Service Contract.
There are various operations to manipulate tasks like GetTasks, CreateTask, etc.  but if you remember REST Design principle 1, it said Resources should be identified uniquely using URI’s,  these operations are translated to URIs using WebGet () and WebInvoke attribute. WebGet is for Http Get and WebInvoke is for Post, Put and Delete.
Also we have defined the request and response message format as XML here. All this is possible because of the System.ServiceModel.Web assembly

Now let’s take a look at the TaskManagement.svc.cs which has implementation of the interface.
Here we have simple list which we are populating with tasks in constructor and then manipulating it in various respective methods.

TaskManagement.svc Markup
Let’s take a look at the mark up, we have not mentioned any service host class here.

Finally let’s take a look at the .config file System.ServiceModel section where we define the configuration for service.
If you observe the binding, we have defined explicitly webHttpBinding and behavior as webHttp, which makes accessing the service over http possible.
Now browse the service by rt.clicking the page
Let’s access operations in browser.

GetTasks http://localhost:38161/TaskManagement.svc/Tasks
GetTask for a specific owner. Since we defined the response format for this as Json we will get a javascript file…let’s save…open it and see…

What you showed me is the server side logic. How will the client make calls to such REST services? 

Sudhanshu: Sure. Let’s take a look at how we consume the REST Services in client applications using WebChannelFactory.

Demo 2 – Consuming REST in Asp.Net using WebChannelFactory (WebChannelFactoryClient project)

Add assembly System.ServiceModel.Web 

First I add the reference of System.ServiceModel.Web which makes the WebChannelFactory classes available then I have to add the web reference of TaskManagementService assembly so that I can have stub or contract of the service on the client side and can access operations.

WebChannelFactoryStyle.aspx.cs Page load
In the page load, I create the instance of WebChannelFactory by providing the URI of the service and then call the CreateChannel to get the channel reference.  Once I get the channel reference I can access all the methods of service.

Let’s set the WebChannelFactoryStyle.aspx as the start page and run it.
Run by browsing.

Let’s try Get, Insert, Delete operations from this application rendered in browser.

This is good, but to me this looks like the way I add reference and invoke SOAP based services. This doesn’t looks like pure REST to me?

Good catch, so you are paying attention haaaa haaa. This can be called low rest implementation. Let me quickly show you a high rest implementation.
Demo – HttpWebRequestStyle.aspx (HttpWebRequestClient project)
No reference of Task Management

We don’t need the reference to TaskManagementService here.
httpWebRequestStyle.aspx.cs, GetAllTasks
We use  httpWebRequest and HttpWebResponse objects from System.Net namespace
Let’s take a look at the GetAll Tasks method.
We create a HttpRequest object by passing the Uri , define the Request method as GET and then read the response stream and bind it to XML UI control.

Similarly for Insert, we use the POST method and write to request stream.
Browse the httpWebRequestStyle.aspx…..

Atul: So far so good. But with SOAP WSDL, I can easily obtain the invocation details of services. Is there any such support with REST?
: Yes. Let me introduce you to REST Starter kit.

REST Starter kit (Slide 17)
The rest starter kit is free and can be downloaded from codeplex site. It has some nice features which simplifies REST services development. It provides Service host which provides the automatic endpoint and one doesn’t need to specify address, binding and contract explicitly in .config file. It also provides attributes like WebCache for caching and WebHelp for help on services, which provides you the invocation details of services similar to WSDL.
For improving developer productivity it provides templates for singleton/collection, http/ POX, ATOM publishing and feed services.

Sudhanshu: Before you ask, let me show you a quick demo
Demo REST starter kit
(RSKT_RESTTaskManagementService project) (Slide 18)
First and foremost you add the assembly  for REST Starter kit, Microsoft.ServiceModel.Web and .extensions

IManageTasks.cs -WebHelp and WebCache
Let’s take a look at WebHelp and WebCache attributes defined in IManageTasks.cs
WebHelp provides help and WebCache help maintain the cache. The caching is defined through <caching> attribute in web.config file

TaskManagement.svc.cs  GetAllTaskByOwner  - Protocol exception
The protocol exception class is useful in translating any clr exceptions into HttpError codes and messages. Here I am checking for business condition as OwnerName equals ‘xxx’ and raising alarm by throwing exception. The Protocol exception helps translates that into Http Error codes.
The key thing to note here is ServiceHost in the TaskManagement.svc markup file. The Service host make it possible to not have any configuration related to endpoint or behavior defined in .config file.
Let’s run the TaskManagement.svc and see how it works


1)      WebHelp – it provides WSDL like information in the context of REST services…like which uri to use to access the resource, what does each Uri does, formats in which the information to send and receive.

2)      GetAll Tasks – Demonstrate it for caching….


if you keep refreshing the web page for above request, you will observe the page doesn’t refresh for 30 seconds. This is because of the WebCache attribute on the GetAllTask method and corresponding settings in .config section

3) By owner – obtain task by owner by accessing the following url

4)Protocol exception –  type ‘xxx’ as user name and it throws protocol exception which is similar to Http Get request.

Atul: Alright. That’s lot of insight that you have provided, but here’s another question for you. When I work on architecture of an application, I need to think about aspects like security, transaction, reliability etc.
Sudhanshu: Atul, I knew that was coming.. haa haa.

Security (Slide 19)
SOAP provides WS-Security. With REST same level of security can be achieved by using https and also by using user or developer tokens. “Access Id” (private key) and “Secret Access Key” (shared key) together is used to secure services.
Digest, basic, Hash message Authentication Code (HMAC ) can be used for authentication.
HMAC is recommended for enterprise application authentication.

Reliability and Transaction (Slide 20)
Reliability can be achieved using http Idempotent put operation and Transactions can be achieved by treating Transaction itself as a resource.
Create Transaction (use POST), Commit transaction using PUT and rollback using DELETE.
Retrieve transaction using GET.
Atul: Sudhanshu, we have had some interesting discussion so far but one thing that is still bugging me is, if this is being used anywhere or are we talking about a technology that looks good on paper or in books? Are there are any real world implementations?
Sudhanshu: oh god Atul. You have a never ending list of questions. Let me give you some real world scenarios
Let’s revisit the distributed architecture viewpoint.

Distributed architecture view point (Slide 20, 21)


From 2005 onwards with emergence of Web 2.0, social networking, software as a service and the more recent cloud based solutions, REST as an architectural style is actively considered as an option for such implementations.  This is primarily because REST. 
*      Is Simple and http based, which makes it highly interoperable.
*      Provides improved Response time and reduced Server load
*      Requires less client side vendor software
*      Easy to implement and consume and hence have relatively low entry barrier as against SOAP
With this, REST has become light alternative to SOAP J

Adoption, Commercial applications (Slide 22)
Amazon has both REST and SOAP interfaces, 85% of their usage is REST interface.
Amazon’s S3 (Simple Storage Service), Flexible Payment, Queue, Search Service exposes both REST and SOAP interfaces. All Microsoft Azure Cloud Services are REST based.
Google, Yahoo services, Flickr, Facebook, Twitter are built using REST services.

Atul: Are there any guidelines for selecting REST over SOAP?
: Yes, there are.

SOAP vs REST? When to use what? (Slide 23)
Use SOAP when you are developing mission critical applications which needs high security, reliability, needs multiple transports, and are highly transactional in nature.

Use REST when interoperability of the application is highly needed, performance is critical, apps. Need to be accessed from multiple devices, needs high scalability and faster time to market with moderate security, reliability and transaction requirements.

That’s great Sudhanshu. This checklist will come very handy and I should say that REST to me is now demystified.

Sudhanshu : Atul, I am glad that REST is Demystified to you.

Dear Readers, we hope it is Demystified to you too. Following are some of the references we have referred to. Appreciate if you log your comments on to the post.

*      Dr. Fielding’s Dissertation
*      WCF Screencast
*      REST Starter kit
*      ADO.Net data services



Thanks for this great post.

Your slide 15 made me think about one common misconception: folks think that you need the WCF REST Starter Kit in order to build REST-based services with WCF. Of course that is not the case; since .Net 3.5 we offer first-class support for REST-style services out of the box. The starter kit is an opportunity for the team to explore new ideas that might make it into the framework. I think that's an important point to articulate since the fact that the starter kit is not an officially supported release can put some folks off.

Thanks again for posting this.

Many Thanks Yavor for acknowledging. I am glad you liked the post.

Post a comment

(If you haven't left a comment here before, you may need to be approved by the site owner before your comment will appear. Until then, it won't appear on the entry. Thanks for waiting.)

Please key in the two words you see in the box to validate your identity as an authentic user and reduce spam.

Subscribe to this blog's feed

Follow us on

Blogger Profiles

Infosys on Twitter