In the ever-evolving world of web services, RESTful APIs have become the go-to choice for many developers. However, the tech landscape is diverse, and you'll often encounter legacy systems or enterprise platforms that still rely on SOAP APIs. If you're a REST aficionado facing the challenge of integrating with a SOAP-based service, don't worry – we've got you covered!

This guide will walk you through the process of building a SOAP API integration, leveraging your existing REST knowledge. We'll explore the key differences, tackle common hurdles, and provide you with practical, actionable steps to successfully bridge the gap between REST and SOAP.

‍

Why SOAP Still Matters

While REST has gained immense popularity, SOAP (Simple Object Access Protocol) continues to play a crucial role in many enterprise environments. Several major platforms in human resources, applicant tracking, accounting, and payment solutions still utilize SOAP, including:

1. Sage X3
2. Salesforce
3. Workday
4. PayPal

As a developer, expanding your toolkit to include SOAP integration skills can open up new opportunities and ensure you're prepared to work with a wider range of systems.

‍

SOAP vs REST: Key Differences

Before we dive into the integration process, let's quickly highlight some key differences between SOAP and REST:

1. Data Format: 

• SOAP uses XML exclusively
• REST supports multiple formats (JSON, XML, etc.)

2. Protocol:

• SOAP is a protocol
• REST is an architectural style

3. Service Definition:

• SOAP uses WSDL (Web Services Description Language)
• REST typically uses OpenAPI/Swagger

4. Flexibility:

• SOAP is more rigid and standardised
• REST offers more flexibility in implementation

5. Performance:

• OAP messages tend to be larger due to XML overhead
• REST can be more lightweight, especially with JSON

Understanding these differences will help you navigate the SOAP landscape more effectively.

‍

A Practical Example: Integrating with Workday's SOAP API

To illustrate the integration process, we'll use Workday's Human Resources web service as our example. Workday is a popular enterprise management platform that offers SOAP, REST, and WSDL interfaces.

Let's break down the integration process into manageable steps:

‍

Step 1: Understand the WSDL

The Web Service Description Language (WSDL) is the backbone of a SOAP service. It's an XML document that describes:

• Available endpoints
• Operations supported by each endpoint
• Request and response structures

Think of WSDL as the SOAP equivalent of OpenAPI/Swagger in the REST world. Your first task is to locate and analyze the WSDL for the Workday Human Resources service.

‍

Step 2: Decode the XML Schema

Once you have the WSDL, you'll need to extract the XML schema for your desired operation. For our example, let's look at a simple operation to retrieve employee information:

<bsvc:Employee_Get xmlns:bsvc="urn:com.workday/bsvc"
bsvc:As_Of_Date="2017-09-21" bsvc:As_Of_Moment="2023-09-18T23:18:33"
bsvc:version="string">
  <bsvc:Employee_Reference>
    <bsvc:Integration_ID_Reference bsvc:Descriptor="string">
      <bsvc:ID bsvc:System_ID="string">string</bsvc:ID>
    </bsvc:Integration_ID_Reference>
  </bsvc:Employee_Reference>
</bsvc:Employee_Get>

‍

This XML snippet defines the structure of a request to fetch employee data. You'll need to populate this structure with actual values when making your API call.

Step 3: Craft Your SOAP Request

A complete SOAP request consists of several elements:

1. SOAP Envelope: The root element of the XML document
2. SOAP Header: Optional element for metadata (e.g., authentication)
3. SOAP Body: Contains the actual request payload
4. SOAP Fault: Optional element for error handling

Here's how you might structure a complete request to fetch employee data:

<soapenv:Envelope
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:bsvc="urn:com.workday/bsvc">
  <soapenv:Header>
    <!-- Authentication details go here -->
  </soapenv:Header>
  <soapenv:Body>
    <bsvc:Employee_Get bsvc:As_Of_Date="2024-01-01"
    bsvc:As_Of_Moment="2024-09-01" bsvc:version="1.1">
      <bsvc:Employee_Reference>
        <bsvc:Integration_ID_Reference bsvc:Descriptor="?">
          <bsvc:ID bsvc:System_ID="?">Jhon Nolan</bsvc:ID>
        </bsvc:Integration_ID_Reference>
      </bsvc:Employee_Reference>
    </bsvc:Employee_Get>
  </soapenv:Body>
</soapenv:Envelope>

‍

Step 4: Handle Authentication

Many SOAP APIs, including Workday, use WS-Security for authentication. You'll typically include your credentials in the SOAP Header. Here's an example:

<soapenv:Header>
  <wsse:Security soapenv:mustUnderstand="1"
  xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"
  xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
    <wsse:UsernameToken wsu:Id="UsernameToken-1">
      <wsse:Username>your_username</wsse:Username>
      <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">your_password</wsse:Password>
    </wsse:UsernameToken>
  </wsse:Security>
</soapenv:Header>

‍

Step 5: Make the API Call

Now that we have our request structure, let's use Python to send it to the Workday API:

import requests

url = "https://your-workday-instance.workday.com/ccx/service/your_company/Human_Resources"
headers = {'content-type': 'application/soap+xml'}

payload = """
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:bsvc="urn:com.workday/bsvc">
   <soapenv:Header>
      <!-- Authentication details here -->
   </soapenv:Header>
   <soapenv:Body>
      <bsvc:Employee_Get bsvc:As_Of_Date="2023-01-01" bsvc:As_Of_Moment="2023-09-01" bsvc:version="1.1">
         <bsvc:Employee_Reference>
            <bsvc:Integration_ID_Reference bsvc:Descriptor="?">
               <bsvc:ID bsvc:System_ID="?">John Doe</bsvc:ID>
            </bsvc:Integration_ID_Reference>
         </bsvc:Employee_Reference>
      </bsvc:Employee_Get>
   </soapenv:Body>
</soapenv:Envelope>

‍

response = requests.post(url, data=payload, headers=headers)
print(response.text)

‍

This script sends a POST request to the Workday API, including our SOAP envelope in the request body.

‍

Step 6: Parse the Response

The API will return an XML response wrapped in a SOAP envelope. You'll need to parse this XML to extract the data you need. Python libraries like `xml.etree.ElementTree` or `lxml` can help with this task.

Best Practices for SOAP Integration

1. Use SOAP libraries: For more complex integrations, consider using SOAP-specific libraries like `zeep` for Python.
2. Error handling: Pay attention to SOAP Fault elements for detailed error information.
3. Caching: Unlike REST, SOAP doesn't support HTTP-level caching. Implement application-level caching if needed.
4. Security: Always use HTTPS and follow best practices for handling credentials.
5. Testing: Use tools like SoapUI to test your requests before implementing them in code.

‍

Wrapping Up

Integrating SOAP APIs into your REST-centric world might seem daunting at first, but with the right approach, it's a skill you can master. By understanding the key differences and following a structured process, you can confidently tackle SOAP integrations and expand your development toolkit.

Remember, while SOAP may seem old-school, it's still a critical part of many enterprise systems. Embracing it alongside your REST expertise makes you a more versatile and valuable developer.

Need help with your integrations? The integration experts at Bindbee are here to assist you! Whether you're dealing with REST, SOAP, or a mix of API types, Bindbee can streamline your integration process. Our unified API approach simplifies connecting multiple systems, saving you time and resources. Reach out to us to learn how we can help you build robust, efficient integrations for your business needs.