What is a SOAP API?
Whenever your application interacts with another application or service, it does so through a web API. Popular API types include REST and GraphQL, but there is an older and still popular type known as Simple Objects Access Protocol (SOAP).
SOAP is more common in corporate and enterprise environments, but still shows up in web services that have been around for a long time. Especially those that are highly stable and where security is important. On the surface, SOAP implementations work the same way as other web APIs. A request is sent from a client to a server. The server processes it and then sends a response. Where it differs is in the implementation.
What is SOAP?
Where REST and GraphQL are architecture styles, SOAP is a standardized protocol. It is managed and maintained by the World Wide Web Consortium (W3C), but that wasn't always the case. The original implementation came to be in 1998 by a team at Microsoft, but it didn't become publicly available until 1999. In 2003 they released version 1.2 of the specification. This became the official W3C standard and is the basis for how SOAP is used today.
When thinking of web service APIs, we often think of sending JSON over HTTP. SOAP can use a variety of transport methods. In addition to HyperText Transfer Protocol (HTTP) and its secure version (HTTPS), it can also use Simple Mail Transfer Protocol (SMTP) which is commonly used in email applications. This variety allows it to be used across many platforms, including those that don't support HTTP. That said, many active implementations rely solely on HTTP/S.
IT also differs in that it does not use JSON. SOAP requires the use of Extensible Markup Language (XML). You may be familiar with XML as the basis for HyperText MarkUp Language (HTML). XML, like all markup languages, are used to describe the content they surround. This results in a highly detailed message with clearly defined fields, but it also means a more verbose message.
Anatomy of a SOAP message
While XML allows for data to be described any way you like, the SOAP schema requires a specific structure around that data. The SOAP message format is made up of four parts.
- Envelope : This part identifies the message as a SOAP message.
- Header : Information about the message. Think of the header as metadata for the message, like authentication details. If it were a real-world letter, it may contain the recipient, sender, and postage details. The header is optional.
- Body : The content of the message. This area is used for both the request and the response—depending on the direction of the message.
- Fault : This part stores information about any errors that occur in the request or response. The fault is contained within the body when an error occurs. It is also optional.
The envelope and body are the two required parts of a SOAP message. Added information can be added through the header, and error messaging can occur by including the fault.
From the official specification, a message may look something like this:
<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope">
<env:Header>
<n:alertcontrol xmlns:n="http://example.org/alertcontrol">
<n:priority>1</n:priority>
<n:expires>2001-06-22T14:00:00-05:00</n:expires>
</n:alertcontrol>
</env:Header>
<env:Body>
<m:alert xmlns:m="http://example.org/alert">
<m:msg>Pick up Mary at school at 2pm</m:msg>
</m:alert>
</env:Body>
</env:Envelope>
Since the fault lives in the body when an error occurs, the message format changes slightly to accommodate faults. For example:
<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope"
xmlns:m="http://www.example.org/timeouts"
xmlns:xml="http://www.w3.org/XML/1998/namespace">
<env:Body>
<env:Fault>
<env:Code>
<env:Value>env:Sender</env:Value>
<env:Subcode>
<env:Value>m:MessageTimeout</env:Value>
</env:Subcode>
</env:Code>
<env:Reason>
<env:Text xml:lang="en">Sender Timeout</env:Text>
</env:Reason>
<env:Detail>
<m:MaxTime>P5M</m:MaxTime>
</env:Detail>
</env:Fault>
</env:Body>
</env:Envelope>
Implementing with WSDL
While SOAP can be complex to write due to the verbose nature of XML, many implementations take advantage of Web Services Description Language (WSDL). A WSDL document describes the entire web service, in XML, that can then be used to scaffold out services and client code. It can also describe types and expectations for the SOAP messages. It can be considered an agreement between the client and server to ensure that both understand how to communicate.
Extensibility and Security
SOAP's core has many uses, but when features need to be added they can be done so easily due to its extension system. SOAP works nicely with many standard protocols, and in particular any that are prefixed with WS. One such protocol is WS-Security.
WS-Security allows SOAP APIs to add additional encryption. Rather than just the transport being secure, like HTTPS, the message itself has a security layer. This makes it very appealing to financial institutions. While the same can be achieved in other architectures, like REST, they often rely on custom implementations and lack a shared standard.
Should you use SOAP today?
Advantages :
- The variety of available transport protocols, such as HTTP and SMTP, as well as the ability to adapt SOAP to work on other protocols like TCP make it useful in a variety of contexts that may not support HTTP.
- When used with HTTP, SOAP works through firewalls that may block other protocols.
- The XML style makes internationalization easier as there are clear descriptions of message values.
Disadvantages :
- The verbose nature of XML, and the need to serialize and parse when sent through HTTP, make it slower and more bandwidth-intensive.
- Many modern APIs have migrated toward REST, GraphQL, or other messaging protocols.
If you are building a new API today or choosing between existing APIs, SOAP is unlikely to be the best option. Modern development stacks are not designed to handle SOAP, and the ecosystem around the protocol is considerably smaller than the competing approaches.
