Common Cases When Using SOAP Makes Sense

This post was originally published on the Nordic APIs blog as “Common Cases When Using SOAP Makes Sense”. These days when discussing web APIs, a RESTful approach is usually assumed. While this modern architectural paradigm is often used, it isn’t always the best tact depending on the job at hand. The fact is that SOAP is still being used quite a lot today. While not all problems can be elegantly solved with SOAP, it may still be the best choice in some specific situations. Crazy talk? It’s true!

In this article, we offer different scenarios where using SOAP not only makes sense but might even be the best available option. Operations related to billing, calculation of transportation routes, and banking are good examples of cases that could benefit from using SOAP’s features.

What makes SOAP powerful is that it is independent of any specific transport layer. This means that it is not restricted to solely transmitting over HTTP (as does REST), allowing communication with other protocols. Using SOAP over SMTP, for instance, lends itself to the rapid development of an API that requires asynchronous communication over a flaky channel. Alternatively, REST-based APIs attempting similar functionality will require one to write a lot of code and deploy a lot of infrastructure.

We’ll also define stateless and stateful operations and how SOAP can help create workflows and transactions. Let’s begin by exploring how formal, machine readable contracts are sometimes needed to guarantee that operations are performing as expected, and how this can be easily achieved with SOAP.

Formal Contracts Within SOAP Reduce Misinterpretation #

Some situations applications require a formal contract between the web service provider and its consumers. SOAP is helpful because this process is clearly defined, leaving no room for misinterpretation. A formal contract is usually needed on mission critical apps mostly used on a large scale and affecting a large number of consumers. Examples include:

• Billing: telecommunication operators, for instance, connect numerous systems in order to identify client consumption and generate billing information.
• Navigation: transportation and shipping companies combine information from different sources in order to calculate the best routes.
• City management: anything from traffic lights to sewage systems where interoperability needs to work in a predictable fashion.
• Electric power transmission: electricity companies change the way power arrives at homes by reading sensor data and remotely changing electricity routing.

SOAP has the ability to describe and make consumers follow formal contracts by using the Web Services Description Language or, in short, WSDL. WSDL is an XML-based definition language used to describe what a web service provider is offering and how it should be consumed. XML employs the following terminologies:

• Service: a description of the service, including its name, namespace, available documentation, and information about existing endpoints.
• Endpoint: information describing an endpoint, including its name, namespace, its address and any available documentation. Endpoints also let you define extensions which bring different functionality.
• Binding: description of how to actually consume the web service, from a message and transmission protocol point of view.
• Interface: information about the sequence of messages that a provider exchanges with consumers. Interfaces can be extended to allow inheritance.
• Operation: a group of related messages exchanged between parties. Rules that define how messages are passed are described by the message exchange pattern.
• Type: description of the data types allowed on an operation. To avoid soft-typing, all data types must be defined by the contract.

As you can see, everything is clearly defined by a machine readable contract. Leaving no room for misinterpretation means that all Web service calls have expected outcomes and side effects are minimized. This is the perfect scenario for situations where you can’t immediately control the output of an operation because it works in an asynchronous way.

SOAP Can Handle Time-Consuming Processes #

Expensive calculations, gathering massive data, and the amalgamation of a result from those constituent parts are time-consuming processes. Rather than keeping the user waiting while this result is derived, an asynchronous approach will immediately return a pending result to the caller, allowing other operations to be triggered in the interim. This can be particularly useful in situations that involve a chain of operations being carried out by the provider. Such operations may include:

• Provisioning and de-provisioning accounts: these operations usually involve communicating with a range of services that can take a long time to respond. In the telecom market, de-provisioning an account might take hours or days to complete.
• Media processing: this is the type of operation usually performed in the media industry. Converting large video files into different formats or extracting metadata cannot be accomplished synchronously.
• Calculating routing paths: due to the vast amount of information, these operations usually take a long time to process.

Asynchronous Operations Require More Than HTTP #

The HTTP protocol is not well suited for asynchronous situations because it can’t easily interact with the client-side processing handled by the parties performing the operation. Using HTTP involves polling on either the provider or consumer side, which can delay the process even more when callers are behind firewalls or without constant connectivity. Anticipating these scenarios, it’s better to use communication protocols that are suited for this reality. It turns out that SOAP supports different communication protocols:

• SMTP: SOAP can easily work with SMTP, the protocol responsible for handling all email communication. SMTP is, by nature, a fully asynchronous protocol with a built-in retry and delivery notification system. SOAP SMTP support works by just embedding SOAP envelopes inside SMTP messages.
• XMPP: Another option suitable for publisher-subscriber architectures is to use SOAP over XMPP. The Extensible Messaging and Presence Protocol, or XMPP, is well known for being used on chat systems but is often chosen in situations where there are many entities interested in being notified about the result of a single operation.

In short, asynchronous operations are present in more situations than one might have first thought. By using SOAP on top of proven asynchronous communication protocols, developers can effectively manage web service communication when a response isn’t readily available. However, to handle complex, chained operations, asynchrony is not enough. For that you will need to keep track of a set of operations and group them into a transaction.

SOAP Supports Stateful Operations #

Most recent web services follow the stateless standard, meaning that clients don’t care about the state of operations between different calls to the server. However, situations that involve multiple chained operations still require stateful operations to make the whole transaction act as one. Some cases require replicating transactions and even performing a roll-back if needed:

• Bank transfers: these operations usually require communication between multiple banks or branches, involving many calls to various Web services. This process is made easier with a coordinator to keep track of their status. The banking industry typically groups all these operations into transactions.
• Booking a flight: again, different entities and web services need to be called in order to check availability and pricing information. When the final information comes back to the user it might already be outdated, so a transaction with a specific lifetime is needed.

Thankfully, SOAP supports stateful operations. This means that a group of operations can easily be controlled by performing a set of predefined rules. State is transferred between operations so that each party involved always knows how to perform without making additional calls. SOAP implements this with the help of Web Services Extension Specification, or in short, WS. There are many available WS extensions that let you define different aspects related to how messages are transferred:

• WS-Addressing: a standard way of adding message routing information to SOAP headers. Being able to define message routing dynamically is important because communication quality might change while the web service is running.
• WS-ReliableMessaging: ensures that SOAP messages are always delivered, even when there’s a failure on network communication or on a software component. Among other things, this extension lets you say that messages need to arrive at a certain order, which is important in a chain of events.
• WS-Coordination: lets you define a workflow that needs to be executed by all the parties involved in the Web service calls.
• WS-Policy: allows a Web service to advertise their working policies which include Quality of Service, expected response times and security.
• WS-Security: specifies how integrity and confidentiality are enforced on messages. In particular it lets you use different types of message encryption like X.509 certificates, user and password credentials, and SAML assertions.

There are many more WS extensions addressing different needs. Developers can even create their own if needed. This customization is one of the reasons why SOAP becomes attractive when the right conditions are in place.

Conclusion #

Despite all the rumors SOAP is still alive and kicking. This doesn’t mean that you should use it in all situations. By carefully analyzing the problem you’re trying to solve you’ll be able to understand if SOAP is the right match for your API. SOAP is particularly useful in situations involving formal, machine readable, contracts where you need to make sure all the parties are behaving exactly as designed. Asynchronous and stateful operations are two other scenarios where SOAP excels. Because SOAP isn’t tied to a particular communication protocol it’s easy to make it work asynchronously. Creating a stateful Web service shouldn’t be too hard because SOAP can easily be extended and operation state can be maintained between calls.