What Is a SOAP API?

Originally published by Kin Lane on September 16, 2020

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.

Related: The Different Types of APIs

A background of SOAP APIs

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.

When to use SOAP APIs

Related: Use the Postman SOAP client

SOAP utilizes XML as part of a standard communication protocol that allows for the exchange of structured information in distributed environments. SOAP lets applications that are running on different operating systems and in different programming languages communicate with each other.

REST vs SOAP APIs

Related: What is a REST API?

SOAP (also known as Simple Object Access Protocol) is a secure way to build APIs, and it works by encoding data in the XML format. REST (Representational State Transfer) APIs are more flexible, and they support data transfer in different formats, including XML, HTML, plain text, JSON, and more. When comparing SOAP vs REST, both have their benefits and disadvantages.

Benefits of using SOAP APIs

Even though SOAP has very strict implementation guidelines, it is also known for its extensibility. Like other approaches to delivering APIs, SOAP uses HTTP for transport, but 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.

SOAP APIs also provide these other advantages when compared to REST APIs:

• SOAP is language, transport, and even platform independent, whereas REST requires the use of HTTP.
• SOAP is very secure, which makes it perfect for systems that handle sensitive data, such as financial services and online banking applications.
• SOAP works well in distributed enterprise environments, instead of depending on direct point-to-point communication.
• SOAP has built-in error handling features, which makes it easy to understand what happened when a request fails.

SOAP API disadvantages

While SOAP can be extremely useful in certain situations, there are also times where REST may be the better option. Some drawbacks include:

• SOAP does not support caching API calls.
• SOAP is much more complicated than REST, which can have performance implications.
• SOAP is much less adaptable than REST.
• SOAP is usually slower than REST.

SOAP API use cases

Some of the most common use cases for SOAP APIs include:

• Transfers at banks: Bank transfers require communication between different banks or bank branches, which may involve multiple calls to different web services. Security is also extremely important for this use case.
• Booking flights: Much like with bank transfers, different web services must be called to check availability and flight pricing information.
• Billing services: People who work in fields like telecommunication operations need to connect with numerous systems to generate billing information, which often includes sensitive data.
• Navigation companies: Shipping and transport companies need to combine information from lots of different sources to calculate the best routes possible.
• City management: SOAP APIs connect many city management processes to ensure the city is run properly. All of these processes— from traffic light management to sewage system operations—need to work in a predictable way.

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.

If you haven’t already downloaded Postman, you can get it for free here. Once you’ve downloaded Postman, check out this Public SOAP APIs collection page.