Building a SOAP API Integration When You Already Know REST: The Full Walk-Through

Editor's note: This is a series on API-based integrations. Check out Merge if you're looking to add 150+ integrations across HR, ATS, CRM, Accounting, and Project Management platforms with one unified API.

‍

Though RESTful APIs are preferred by many organizations these days for their flexibility, some legacy enterprises, platforms, and systems still use SOAP APIs. SOAP is an older protocol and exchanges data formatted as XML. SOAP is also language and platform agnostic and focuses on remotely accessing and manipulating objects.

A number of human resources, application tracking, accounting software, and payment-solution platforms still rely on the SOAP protocol, including Sage X3, Salesforce, Workday, and PayPal. This poses a challenge for REST API–based organizations that need to integrate with SOAP-based platforms.

In this tutorial, you’ll learn how to put your REST skills to use for integrating your platform with SOAP APIs.

{{blog-cta-100+}}

A SOAP API Example

One of the most popular enterprise management platforms using SOAP APIs is Workday, which provides payroll, human resources, and applicant-tracking services to developers. Its API incorporates WSDL, REST, and SOAP protocols.

If you compare SOAP to REST, integrating with SOAP APIs is not so different from how your organization already uses REST APIs. You’ll make calls to test the Workday human resources web services by carrying out some basic CRUD operations. (This tutorial assumes you already have a Workday user ID and password.)

Following is a high-level overview of the process:

• Check the Workday Web Service Description Language (WSDL) document to see how to call your required web service.
• Extract and interpret the WSDL XML request schema for the required service endpoint.
• Configure the SOAP request header and body structure to add API URL and authentication using your Workday user ID and password.
• Make HTTP connection and call using Postman, SoapUI, and Python (or other languages like Java, PHP, or Ruby).

Implementing a SOAP API Integration with Python

Since many organizations use Python for automating communication between APIs and for API integration, let's use it for this tutorial.

Python’s popular Requests library allows developers to make HTTP request calls to a specific URL. You may already use this library to implement REST API calls and integration with Python, but you can also use it to call SOAP services.

There are more robust libraries like suds and Zeep for interacting with SOAP APIs in Python. For simplicity, though, let’s stick with the Requests library.

Checking WSDL Requirements

WSDL is an XML format for calling a web service that describes the available endpoints, the structure of requests, and the responses to expect. WSDL is a standard format for SOAP API documentation or specification, much like for REST APIs.

You’ll first need to check the WSDL requirements in Workday’s documentation.

You can see the available Workday API services, including the Human_Resources Web services you’ll be using. Click on the Human_Resources link to see the list of specific CRUD operations available and their associated descriptions.

For this tutorial, you’ll be making GET and POST calls to the endpoint using the <code class="blog_inline-code">Get_Employee</code> operation to fetch employee data and the <code class="blog_inline-code">Add_Vaccination</code> operation to create a vaccination record resource for an employee.

WSDL’s are for SOAP web services what Swagger/OpenAPI schemas are for REST-based web services. The JSON contents of Merge API’s OpenAPI schema for HRIS at https://api.merge.dev/api/hris/v1/schema contain many of the same objects as the XML contents of the Workday WSDL, albeit for different HRIS services.

Extracting WSDL XML Request Schema

In the Workday Human Resources services, you’ll see a simple XML sample of the SOAP message body for retrieving employee information from Workday: 

Developers often use tools and environments that can read a WSDL file to find methods and syntaxes for writing the SOAP message payload. SoapUI is one such tool. The image below shows the SoapUI interface after the Human_Resources WSDL file was imported into the SoapUI tool:

Note that a typical SOAP request message structure has some parallels with a REST API request structure. As seen in the above screenshot, the SOAP request contains the following elements:

• A SOAP envelope element, which serves as the root element defining the XML document
• An optional SOAP header element—like a RESTful header— contains specific information like SOAP API authentication, cookie, and user agent
• The SOAP body element containing the actual message (data/payload) for the endpoint
• An optional SOAP Fault element for keeping errors and status data for the message

For more information on the SOAP standard syntax structure, check the W3 Consortium documentation on SOAP binding for HTTP.

SoapUI automatically adds the required elements to the body syntax provided on the Workday website. Next, we’ll configure your request message to point to your organization’s Workday URL—either provided by the platform or available in documentation—with relevant authentication.

Configuring SOAP Request Authentication

If the API call you want to make requires authentication, those details can easily be bundled with the <code class="blog_inline-code">SOAP:Header</code> element. Workday APIs use WS-Security for SOAP API authentication. By using the WSDL endpoint to connect directly to the server, you can add a username field and password to obtain access.

Say your company’s WSDL endpoint URL for Workday is <code class="blog_inline-code">https://MY-COMPANYINSTANCE.workday.com/ccx/service/MY-COMPANYNAME/Human_Resources</code> and your username is <code class="blog_inline-code">UserName@MY-COMPANY</code>. You can send a fetch request to get the details of an employee in your organization with the system ID <code class="blog_inline-code">Gil Feig</code> from 2019 to date with a version of the message snippet above.

Below, the header and the SOAP body elements have been modified and wrapped inside a SOAP envelope.

Next, we’ll write a Python script to send the request.

Making an HTTP Request

Combining all the above steps in a Python script, your client can make a request to the Workday API server and get a response. For your Workday instance, the script to fetch an employee data will look like this:

You should get a response from the server specifying employee data as an XML response body wrapped in a SOAP envelope, formatted this way, and an HTTP 200 response code.

You’ll note some differences here between REST and SOAP APIs. In contrast to REST API response bodies that can hold different data formats like JSON, stylesheets, PNG, and documents, SOAP APIs only return XML data in the response.

In addition, REST makes use of HTTP verbs like GET, POST, PATCH, PUT, and DELETE to send requests for CRUD operations. The HTTP GET method allows for caching of the response data coming from web services. When SOAP uses HTTP protocol as its transfer mechanism, requests are mostly sent via the HTTP POST method. As a result, there is no caching done at the HTTP level for SOAP HTTP requests.

To complete your integration, use your preferred tool to parse the XML data in the server response and build your solution on top of the API connection.

Making a Request to Create a Resource

Now you’ll send a POST request to the SOAP API endpoint to create a new resource on the server-side. You’ll add a vaccination record for an employee using the same technique you used to make the GET request but with a different request body, per the SOAP request specification in the WSDL file.

As before, the response will return an XML body wrapped in a SOAP envelope.

Conclusion 

SOAP APIs may seem like a challenge to work with, but even if you’re more familiar with REST APIs, you can still integrate your platform with a SOAP API platform. This added flexibility will increase your organization’s ability to work with legacy platforms as well as add some needed skills to your toolbox.

If you’d like an easier way to accomplish such an integration, though, consider Merge. Even if the original platform uses SOAP, Merge’s RESTful API platform offers a unified way to integrate all of your company’s systems, from human resources and payroll to recruiting and accounting. We provide authentication, logs, issue detection, and automated alerts to help your business save resources. You can sign up for a free trial or request a demo.