You can get lost in a sea of acronyms when deciding what type of technology or strategy to use for your web service. When it comes down to it, there are two schools of thought for implementing web services: SOAP and REST.

XML/SOAP

SOAP originally stood for Simple Object Access Protocol, and has become the standard for exchanging messages over a service. It uses messages enveloped in an special XML format (also called SOAP). Requests and responses come in a nice, standard XML package which can easily be parsed and handled by most programming languages. Messages can be exchanged using standard HTTP GET or POST requests/responses. However, SOAP messages can readily be exchanged over any generic transport method (e.g., TCP/UDP, SMTP, JMS, to name a few), so it is not limited to using HTTP/HTTPS.

Here’s an example request and response from a SOAP service that simply checks if a product is in stock or not.

SOAP Request:

<?xml version="1.0"?>
<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope"
xmlns:s="http://tempuri.org/service">
<env:Body>
<s:GetProductListing>
<s:ProductId>42</s:ProductId>
</s:GetProductListing>
</env:Body>
</env:Envelope>

SOAP Response:

<?xml version="1.0"?>
<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope"
xmlns:s="http://tempuri.org/service">
<env:Body>
<s:GetProductListingResponse>
<s:ProductId>42</s:ProductId>
<s:ProductName>Rainbow Stickers, 10 pack</s:ProductName>
<s:UnitsInStock>12</s:UnitsInStock>
</s:GetProductListingResponse>
</env:Body>
</env:Envelope>

Here’s how the request would change for other operations:

  • To delete a product: <s:GetProductListing> tag would change to <s:RemoveProduct>
  • To increment/decrement stock amount: <s:GetProductListing> tag would change to <s:ChangeStockAmount>. New child tag(s) would indicate by how much.
  • To create a new item: <s:GetProductListing> tag would change to <s:CreateProduct>. New child tags would describe the details.

HTTP/REST

REST stands for Representational State Transfer. REST uses a standard URI to make a call to the web service. This is simple for a client to build and understand, and can be executed from any client with HTTP request capacity. Since REST operates over HTTP/HTTPS, it uses familiar GET, POST, PUT, DELETE verbs which are usually logically mapped to CRUD operations. Opposing SOAP, the return structure can be in any format. This means you can escape the perceived verbosity of the SOAP standard. Some commonly used options are POX (Plain Old XML) and JSON (JavaScript Object Notation). Often REST web services offer multiple endpoints for different return types. This is a benefit as you can target your request/response types for the intended clients. For example, if you expect to be consumed by Web applications using JavaScript, you might choose JSON as a format to return. This makes it easy on the clients as they don’t have to do special parsing on messages.

HTTP Request:

GET /Product/42

JSON Response:

{
"ProductId": 42,
"ProductName": "Rainbow Stickers, 10 pack",
"UnitsInStock": 12
}

Here’s how the request might look for other operations:

  • To delete a product: DELETE /Product/42
  • To increment/decrement stock amount: PUT /Product/42/Add/# and /Product/42/Remove/# where # is how many to add/remove
  • To create a new item: POST /Product [body contains JSON for new product]

Pick One…

Use SOAP when:

  • All you need is simple operations, like read only methods
  • Implementing a one-way or one-object service for something like data exchange or transfer
  • You want finer control over the specific transport of data, or can’t always use HTTP
  • Rigid specifications need to be enforced on incoming requests, and you want to minimize additional documentation needed for use
  • You can rely on client ability to parse XML, or more preferably SOAP itself
  • You need built-in error handling when things go wrong with requests

Use REST when:

  • Operations are complex, like create/read/update/delete on objects
  • Implementing a multi-faceted service for a variety of different objects
  • You want to easily and quickly target a variety of consumer end user devices as clients
  • Requests are generally stateless, like call and response compared to a conversation
  • Your clients may have limited bandwidth or processing power
  • You can leave it up to the client to get their requests correct and to deal with problems

…Or Don’t!

Don’t know what you should pick? No worries. You can mix and match. There’s no reason you can’t offer both types of services, or combine them. You can return SOAP formatted objects over a REST service, for example. From a Microsoft standpoint, combining the types of services is increasingly converging in WCF (Windows Communication Foundation). Generally, most people agree that while REST looks like the “future” of web services, the SOAP standard is not going away. It will continue to be used over REST as a standard format, and in situations where HTTP/HTTPS transport can’t work. IMO, I think the two will fully merge into a single REST/SOAP hybrid that allows the simplicity and format flexibility of REST, with the security and reliable standards of SOAP.

Like this post? Share it!