API 101: What Is a SOAP API?

Kin Lane

September 16, 2020· 3 mins

Simple Object Access Protocol (SOAP) is a message specification for exchanging information between systems and applications. When it comes to application programming interfaces (APIs), a SOAP API is developed in a more structured and formalized way. Think of SOAP as being like the national postal service: It provides a reliable and trusted way to send and receive messages between systems (and within enterprise applications). It is older, established, and dependable—but it can be slower than competing architectural styles like REST. (Learn more fundamentals by reading our What Is an API? and What Is a REST API? intro posts.)

SOAP was a standard that emerged in the late 1990s to give businesses the ability to move data around between corporate networks. It was introduced just as the web was maturing, and while it does use HTTP primarily as a transport for the messages being passed around, its architectural patterns are not as closely aligned with HTTP as REST; SOAP can also employ other protocols. While REST is more of a style, SOAP gives you much more guidance on the structure of the request and response, as well as the message content and how it will be encoded. Simply put, using SOAP when designing APIs focuses on the message, whereas using REST when designing APIs focuses on defining them as resources.

SOAP uses XML as the data format for messages being sent and received by an API client, and it provides four distinct dimensions to the API protocol:

• Envelope: Defining the structure of the message.
• Encoding: Rules for expressing the type of data.
• Requests: How each SOAP API request is structured.
• Responses: How each SOAP API response is structured.

Even though SOAP is very strict in its implementation guidelines, it is also known for being extensible. SOAP allows the structure of messages to be augmented and evolved to meet specific requirements. Like other approaches to delivering APIs, SOAP uses HTTP as a transport, but one of its strengths is that it can also leverage simple mail transport protocol (SMTP), transmission control protocol (TCP), and user data protocol (UDP) to pass messages back and forth. This allows for more flexibility when it comes to moving data, content, and media systems and applications.

A SOAP API example

Let’s take a look at an example of a SOAP API in an ISBN book validation service, which provides validation using a simple URL:

• http://webservices.daehosting.com/services/isbnservice.wso

This ISBN validation service uses a POST HTTP method to pass the following structured snippet of XML to the service using the body of the HTTP request. It provides a structured request for the server to process and return a response:

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
 <soap:Body>
  <IsValidISBN10 xmlns="http://webservices.daehosting.com/ISBN">
   <sISBN>0-19-852663-6</sISBN>
  </IsValidISBN10>
 </soap:Body>
</soap:Envelope>

This then returns the following XML response, which confirms that the ISBN number is valid:

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <m:IsValidISBN10Response xmlns:m="http://webservices.daehosting.com/ISBN">
         <m:IsValidISBN10Result>true</m:IsValidISBN10Result>
      </m:IsValidISBN10Response>
   </soap:Body>
</soap:Envelope>

This ISBN validation service uses a standardized SOAP envelope to pass a structured message as part of the request, resulting in a standardized response sent in the same way. The SOAP response structure makes it easy for developers to understand and put to work in their applications and integrations.

While this particular use case is specific to validating ISBN numbers for books, SOAP APIs can be applied to making any data, content, media, and algorithms available between systems, and within applications. SOAP essentially provides an industrial-grade format for automating how different business messages communicate across daily operations.

Conclusion

The SOAP protocol provides a much more solid foundation for APIs than the looser REST approach, but it can come with a cost. SOAP can make it slower to evolve and iterate APIs, and it can take longer to onboard new developers who aren’t familiar with SOAP’s older methods. Still, it’s a cost that is worthwhile for backbone applications and integrations that the enterprise depends upon. Remember that national postal service comparison? With its envelope, encoding, request, and response structure (as well as versatility with protocols like HTTP, TCP, UPD, and SMTP), SOAP remains a dependable way to define and operate APIs across the enterprise at scale.