APIs 101: What Is SOAP (Simple Object Access Protocol)?

SOAP is good for getting clean, but it’s also a powerful protocol for standardized messaging and web communications! So, what is this technology, and how does it work? Below, we’ll dive into this topic and give you some actionable insight into how API developers use SOAP in practice.

What is SOAP?

In the early days of web communications, a lot that we take for granted today was still being worked out. In this relative technological wild west, substantial growth forced developers to begin looking at the long-term viability of the structure underlying the languages and frameworks commonly used. Out of this need for structure and a formal definition arose SOAP.

SOAP, or Simple Object Access Protocol, is a messaging protocol specification that offers a structured XML messaging format for triggering remote actions or processes on hosts. Put simply, it allows clients to send a message and get a host to do “something.” While this seems relatively simple by today’s standards, there was a time when these standards were not commonplace. Don Box, one of the creators of SOAP (alongside Dave Winer, Bob Atkinson, and Mohsen Al-Ghosein) had this to say about those early days:

“When SOAP started in early 1998, there was no schema language or type system for XML. […] Was SOAP the first attempt to add a behavioral type system to XML? Not at all. I recall scanning the landscape at the time. The existing proposals either assumed a COM type system underneath (unacceptable, since even back in 1998 we knew COM wasn’t the ultimate type system) or were very EDI-like, which would alienate parts of the development community. For that reason, we looked at the existing serialization formats (ASN.1 BER, NDR, XDR, CDR, JRMP) and RPC protocols (GIOP/IIOP, DCE/DCOM, RMI, ONC) and tried to hit the sweet spot that would satisfy the 80% case elegantly but could be bent to adapt to the remaining 20% case.”

From this effort, SOAP would be released first as XML-RPC in June 1998 and then submitted to the IETF in September 1999. Over time, SOAP saw wide adoption as a methodology for connecting clients to web services, especially when those clients need access to specific functions and operations rather than data or data representations.

SOAP in Practice

SOAP defines its message format using XML and most commonly leverages HTTP as its message negotiation and transmission modality. Because SOAP uses a set message format, it is platform agnostic, allowing any system supporting HTTP and XML to connect with other such systems.

The SOAP flow is broadly as follows:

Request formation: A SOAP client creates a request for a function or operation, which is packaged in an XML document.
Request transmission: The client sends the XML document with HTTP to the web server hosting the service in question.
Request routing: The web server routes the message to the appropriate SOAP servlet or application.
Request fulfillment: The request, if valid and credentialed, is invoked.
Response formation: The response is generated and packaged in an XML response.
Response transmission: The response is sent back over the same route to the requester.

SOAP is a strong choice when the operation itself must be exposed. Because SOAP is strongly coupled — meaning that the client and the server have a rigid, predefined contract as to how to operate — a greater amount of control and integrity can be enforced. SOAP also has various ways to extend this contract, with additional (optional) expansions opening up federation, policy enforcement, and more.

These capabilities grant SOAP much control, which is especially helpful for adopting a security-first development mindset. However, this control does come with a cost. One way to look at SOAP is to consider it like a letter in an envelope. It has a predefined format, a structured messaging approach, and an enclosed method of transport. Writing and reading a letter takes effort, but envelopes with letters can carry all sorts of information that cover many use cases.

Other formats, however, are more like postcards — they are lightweight and quick, sure, but they may not be able to do everything a standard letter could. Ultimately, you trade off a lot of control using something non-SOAP, but you potentially gain quite a bit more flexibility.

Example Code

One example of SOAP in practice can be found in the API documentation for Google Ad Manager. Google Ad Manager provides a SOAP XML service that allows functions to be called using various parameters.

The following code is issued to make a request which lists the Ad Units for a given publisher. A query is then wrapped in this request to limit the parentId of Ad Units in the response by a specific attribute parameter:

<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope
        xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
        xmlns:xsd="http://www.w3.org/2001/XMLSchema"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <soapenv:Header>
    <ns1:RequestHeader
         soapenv:actor="http://schemas.xmlsoap.org/soap/actor/next"
         soapenv:mustUnderstand="0"
         xmlns:ns1="https://www.google.com/apis/ads/publisher/v202311">
      <ns1:networkCode>123456</ns1:networkCode>
      <ns1:applicationName>DfpApi-Java-2.1.0-dfp_test</ns1:applicationName>
    </ns1:RequestHeader>
  </soapenv:Header>
  <soapenv:Body>
    <getAdUnitsByStatement xmlns="https://www.google.com/apis/ads/publisher/v202311">
      <filterStatement>
        <query>WHERE parentId IS NULL LIMIT 500</query>
      </filterStatement>
    </getAdUnitsByStatement>
  </soapenv:Body>
</soapenv:Envelope>

The request generates the following response:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Header>
    <ResponseHeader xmlns="https://www.google.com/apis/ads/publisher/v202311">
      <requestId>xxxxxxxxxxxxxxxxxxxx</requestId>
      <responseTime>1063</responseTime>
    </ResponseHeader>
  </soap:Header>
  <soap:Body>
    <getAdUnitsByStatementResponse xmlns="https://www.google.com/apis/ads/publisher/v202311">
      <rval>
        <totalResultSetSize>1</totalResultSetSize>
        <startIndex>0</startIndex>
        <results>
          <id>2372</id>
          <name>RootAdUnit</name>
          <description></description>
          <targetWindow>TOP</targetWindow>
          <status>ACTIVE</status>
          <adUnitCode>1002372</adUnitCode>
          <inheritedAdSenseSettings>
            <value>
              <adSenseEnabled>true</adSenseEnabled>
              <borderColor>FFFFFF</borderColor>
              <titleColor>0000FF</titleColor>
              <backgroundColor>FFFFFF</backgroundColor>
              <textColor>000000</textColor>
              <urlColor>008000</urlColor>
              <adType>TEXT_AND_IMAGE</adType>
              <borderStyle>DEFAULT</borderStyle>
              <fontFamily>DEFAULT</fontFamily>
              <fontSize>DEFAULT</fontSize>
            </value>
          </inheritedAdSenseSettings>
        </results>
      </rval>
    </getAdUnitsByStatementResponse>
  </soap:Body>
</soap:Envelope>

One thing that should be quite obvious from this example is how much metadata is exchanged within requests and responses. SOAP is quite verbose due to its structured format, and while this grants a lot of control and stability, it does have its own drawbacks to consider.

Pros and Cons of Using SOAP

As with any technology, SOAP has some major advantages and disadvantages. Let’s examine these points more closely.

Pros

SOAP has a formalized approach and standard, meaning that SOAP instances are structurally similar across deployment environments and situations.
It works across any protocol and system as long as there is support for HTTP and XML.
Clients have access to functions and operations, not just the representations of the state or the underlying data related to those functions and operations.
With built-in error correction, security, and authorization, SOAP is a strong contender for environments such as banking where high-grade security is required.

Cons

SOAP requires many resources to communicate form and structure — the entire metadata structure is expressed for each request.
Sometimes, you only want to express the state and not the actual functions — in this case, SOAP is a poor choice.
While SOAP is a platform and protocol agnostic paradigm, it only utilizes XML by design, which is limiting to some.
Over time, SOAP has waned in popularity compared to other API styles, meaning developer awareness is not as high as it used to be.

REST, RPC, and More

While SOAP is quite powerful, there are other solutions on the market, and in some cases, those solutions may be more appropriate!

REST: REST, or Representational State Transfer, is an architectural style in which representations of the state of services (rather than the actual functions and operations themselves) are acted upon. Compared to SOAP, REST is typically lighter and simpler to implement.
RPC: RPC, or Remote Procedure Call, is very similar to SOAP, but it tends to be lighter in implementation than SOAP. That said, it can be somewhat limiting due to the design approach. RPC models the method and function as being local to the client rather than acknowledging the XML layer separation, which can raise security concerns in some specific applications.
GraphQL: GraphQL is a query language, so it’s not really fair to compare GraphQL to SOAP. Nonetheless, GraphQL is a very common solution for feeding function results to the end user. The big difference here is the amount of control over the output — in GraphQL, the client determines what they want to see and in what format.

Conclusion

Ultimately, SOAP is one of many potential solutions and can be a solid choice for instances where high control and integrity are required. What do you think of SOAP? Have we missed any major pros or cons? Let us know in the comments below!