SOAP API Examples (With REST API Comparison)

SOAP in the context of APIs is not fragrant nor is it what you use to clean your body. SOAP is a protocol that has enabled developers worldwide to use Web Services, or what we now generally know as APIs.

This article will describe what SOAP APIs are, what they are comprised of, and other characteristics that define and separate SOAP APIs from different types of APIs, like REST APIs.

What is SOAP?

SOAP stands for the widely used Simple Object Access Protocol, a set system of communication and exchanging information in Web Services, applications, and systems.

SOAP APIs put more significance on the message of the data, as you will notice that SOAP APIs have more guidance for developers to set the structure of the request, response, and message content. This makes SOAP APIs very relevant in applications that require sending messages to and fro systems.

What is Unique About SOAP APIs?

There are properties that SOAP APIs possess that make them a different type of API altogether. Here are the significant differences that SOAP APIs demonstrate from other types of API protocols.

XML-based Protocol

XML (eXtensible Markup Language) is a readable language for humans and machines. SOAP APIs rely on this language to encapsulate the data.

Message Structure

SOAP APIs' structure looks like an enveloped email, with specific elements with their respective functions. For this reason, SOAP is considered to be lengthy and heavy to other APIs.

The four signature components of a SOAP API are:

1. Envelope - The outermost element of a SOAP message that contains the rest of the message: the header, body, and fault. The envelope tag is the first and last tag that envelopes the SOAP message.
2. Header - An optional section of the SOAP message that can specify any additional requirements of the message sent, such as authentication details and transaction information. It can widely vary depending on the context of where the SOAP API is used.
3. Body - the main section of the SOAP message that contains the request or the response of the message. This is where applications or systems get the information that they require to carry out their role.
4. Fault - Another optional section of the SOAP message that displays the details of any errors that may arise through the SOAP API's request and response.

ACID Compliance

ACID (Atomicity, Consistency, Isolation, and Durability) is a characteristic that an API may possess. When a SOAP API is said to have ACID compliance, you can expect the data transactions to have these properties:

Atomicity - Data exchange involved in SOAP APIs is treated as a single unit, where the packet is either entirely sent or not at all. If the exchange fails, the data packet is rolled back entirely, leaving the database as it is to maintain the consistency of both systems.

Consistency - Whenever there is any failure during the data transaction, everything is rerolled back to its initial state to prevent damage to both systems' databases.

Isolation - One SOAP API request is treated separately from another in isolation, where they are not done together with other operations. It is done so to ensure that the database's integrity is preserved.

Durability - Any changes, be it an edit, addition, or reduction, will be permanent and will not be altered until the next SOAP API request is processed and completed.

Extensibility

The SOAP structure has become a widely used protocol to solve numerous common problems developers face. Since then, developers have also extended SOAP APIs through a set of specifications known as WS-* (Web Services Specifications). These specifications add additional standards for various aspects of web services, like transactions (WS-AtomicTransacition), and addressing (WS-Addressing).

SOAP vs. REST - The Differences

Many new developers may get overwhelmed with the variety of API types introduced to them. Another very popular API archetype is the REST (REpresenational State Transfer) API, where REST is an architectural style of creating web services.

It is worth understanding more about what is a REST API! Who knows, maybe one day you will design a world-wide used API that developers treasure!

Language Differences

SOAP - Data transactions with SOAP APIs use the XML message format, with a fixed structure to send requests and receive responses.

REST - Data transactions with REST APIs can be in different data message formats, such as XML, JSON, and HTML, allowing for more flexibility.

Error Handling

SOAP - SOAP APIs have specified error cases, which is part of its fault element.

REST - REST APIs have to rely on HTTP status codes to indicate whether the request or response was successful. It is possible to see additional error details in the response body.

HTTP Method Usage

SOAP - SOAP APIs rely on POST HTTP methods for all types of operations.

REST - REST APIs utilize other HTTP methods such as GET, POST, PUT, and DELETE, depending on the scenario that needs it.

Examples of Famous SOAP APIs

Amazon Web Services (AWS) API

AWS originally used SOAP as the primary protocol for its web services but has introduced RESTful alternatives. but SOAP APIs are still supported for some services. For example, the Amazon Simple Queue Service (SQS) initially used SOAP.

Microsoft SharePoint API

Microsoft SharePoint is a collaborative platform that relies on SOAP for its API. Developers used SOAP requests to interact with and manipulate SharePoint data and services.

Salesforce API

Salesforce, a popular customer relationship management (CRM) platform, provides a SOAP API that allows developers to integrate and interact with Salesforce data.

Java API for XML Web Services (JAX-WS)

JAX-WS is a Java-based API for creating SOAP-based web services. It was part of the Java EE (Enterprise Edition) platform and allowed developers to build and consume SOAP web services in Java.

Using Apidog to Import SOAP APIs form WSDL files

To understand and revise SOAP APIs, you can use API platforms to do so. Apidog is a new, powerful API platform that allows developers to import SOAP APIs in the form of WSDL files to edit and debug existing SOAP APIs.

All you need to do is download the app, create an account, and start a new project to begin importing SOAP APIs!

Once you have created a new project, start importing your SOAP APIs by following these steps:

Arrow 1 - Locate the "Settings" button on the vertical sidebar.

Arrow 2 - Locate the "Import Data" tab under "Data Management"

Arrow 3 - Select the "WSDL" button under "Import Data".

After successfully importing the WSDL file, you can follow this next set of instructions to start perfecting your SOAP API.

Arrow 1 - Select the imported SOAP API request (name it something different from other existing API requests that you have made before.)

Arrow 2 - Locate the "Body" subsection.

Arrow 3 - Locate the "xml" small subsection.

Arrow 4 - Start editing your SOAP API message.

Using Apidog to Test Imported SOAP APIs from WSDL Files

Every web service developer needs to test whether their product works after changes are made. Thankfully, Apidog allows developers to create test scenarios for their APIs. Here is a step-by-step guide.

Firstly, locate the "Testing" button pointed out by Arrow 1 in the image above. You should then see "New Test Scenario", pointed out by Arrow 2.

You should then be prompted with this pop-up window, asking you to input a few details about your new test scenario. Once you have filled it out, you can hit the "OK" button on the bottom right corner, or just "Enter" on your keyboard.

Add a step (or many more steps) to your test scenarios by clicking on the "Add Step" section. You should be able to see the image below.

Select "Import from API" from the drop-down menu.

Select all the APIs you would like to include in your test scenario. In the example above, the API called NumberConversionSOAP has been included.

Before hitting the "Run" button to start your test scenario, make sure to change the test scenario environment, which should be "Testing Env", as pointed out by Arrow 1.

Give it a try, and you can see whether your API can meet all your requirements!

Conclusion

REST and SOAP have their differences and similarities, however, they both excel in certain situations, so ensure that you are equipped with the right knowledge!

To learn more about SOAP APIs, check out how you can use the widely known Jakarta SOAP API and implement it in your projects or applications!