CloudDays™ Quick Start – Choosing Between RESTful Web Service, SOAP

Representational State Transfer (REST) is an architecture style or design pattern for creating web services which allow anything connected to a network to something else on the network using Hypertext Transfer Protocol (HTTP).

Typically we think of a RESTful Web Service as one that will get and set data. It works a lot the same way as a web page, but your user doesn’t see the data until it’s time to be displayed.

REST principles are based on the same underlying principles that govern the Web. Those principles are:

User agents interact with resources, and resources are anything that can be named and represented. Each resource can be addressed via a unique Uniform Resource Identifier (URI).
Interaction with resources (located through their unique URIs) is accomplished using a uniform interface of the HTTP standard verbs (GET, POST, PUT, and DELETE). Also important in the interaction is the declaration of the resource’s media type, which is designated using the HTTP Content-Type header. (XHTML, XML, JPG, PNG, and JSON are some well-known media types.)
Resources are self-descriptive. All the information necessary to process a request on a resource is contained inside the request itself (which allows services to be stateless).
Resources contain links to other resources (hyper-media).

SOAP vs REST

When it comes to the discussion interacting with Web Services, you will want to be versed in the alternatives.

Simple Object Access (SOAP) is a protocol specification for exchanging structured information in the implementation of web services in computer networks. SOAP can use HTTP or Simple Mail Transfer Protocol (SMTP) for message negotiation and transmission.

SOAP and REST are aimed at solving a identical set of problems, namely facilitate the interaction between heterogeneous applications in easiest possible manner.

Unlike REST, SOAP is XML-based protocol consists of three parts:

An envelope, which defines the message structure and how to process it
A set of encoding rules for expressing instances of application-defined data types
A convention for representing procedure calls and responses

REST on the other hand is centered around defining a URL and sending and receiving data in the HTTP header and JSON in the message body. You will learn more about how this works in the following posts.

Choosing SOAP or REST

Now whether to choose REST or SOAP does not just depend on the amount of development effort. You should consider some of following factors:

The main advantage of SOAP is that it provides a mechanism for services to describe themselves to clients, and to advertise their existence.
REST is much more lightweight and can be implemented using almost any tool, leading to lower bandwidth and shorter learning curve. However, the clients have to know what to send and what to expect.
Do you need to use SMTP or TCP as your transport layer? If so, you will want to use SOAP.
If you want to include type information about the data, in other words you need to share whether a specific item is a string or int, you may want to consider SOAP. While you can share type information using JSON, this strategy is really not a best practice of JSON.
The consumer of your service. REST are more suitable when you are developing Rich Internet Application (RIA).
Security requirement. SOAP by virtue of being standard driven, offers a very fine grain level tuning of security aspect. You can go to an extent of encoding the individual elements of your SOAP xml message.
JSON is really a for lightweight data exchange and many REST service frameworks offers this very easily out of box.
Technically, you do not need any framework to create a REST web service. I understand that WADL etc came recently to bring in an element of standardization but REST existed even before WADL came.

REST is nothing new, its the way web works. REST frameworks make it very easy.

SOAP is driven by standards and hence there are more constraints to honor when you work with them. So if you use case is simple (well that’s very subjective), go for REST.

It’s typically easier to implement than to SOAP and WSDL based Web services, which are also valuable.

Tools

Lots of tools to help with REST development. You can develop your REST endpoints using ASP.NET WCF or Web API. As I continue the series, I’ll show how you build controllers using Web API in Visual Studio.

Use the browser of your choice to test your urls. Ideally a restful service can be consumed by any browser.

For monitoring I use Fiddler.

I’ve had good success with POSTman REST Client in exercising web services that use REST.

REST ScratchPad lets you enter the data to send to the REST service and view the results of queries along with their headers and response times. It will handle basic authentication and will remember the URLs you’ve used in prior sessions (to avoid having to re-type long URLs).

Getting Started

.NET, Azure

If you are on the Microsoft stack, build yourself a server using the tutorial at Getting Started with ASP.NET Web API 2 (C#). You can build a simple application where you can see the HTTP Requests and Responses. You can download the source code for Web API completed project.

Taking this a step further, if you want to build on Microsoft Azure cloud, see REST service using ASP.NET Web API and SQL Database.

Node.JS

If you are interested in Node.js, you can get started with a tutorial Creating a REST API using Node.js, Express, and MongoDB.

Fiddler

Get Fiddler and then. Take a look at Getting Started with Fiddler to learn how you can configure your server and your client to set up monitoring on remote machines, configure Fiddler to decrypt HTTPS traffic, set the FiddlerRoot trust certificate, configure .NET applications.