⊕ 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.
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.
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.
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.
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.
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.
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.
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.