# Working with SOAP APIs

### Introduction

Some systems still use SOAP APIs (**S**imple **O**bject **A**ccess **P**rotocol) instead of REST APIs. \
SOAP is a messaging protocol that uses XML in order to exchange information between computers.

At Locoia, you can integrate SOAP APIs by configuring Connector Actions with SOAP-specific settings.

***

### Creating the SOAP Request Body

Define a valid SOAP XML payload manually in the Request Body Template using Jinja for dynamic fields.

{% code title="Example Request Body Template" %}

```xml
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:web="http://webservice.example.com/">
   <soapenv:Header/>
   <soapenv:Body>
      <web:getDetails>
         <id>{{ id }}</id>
      </web:getDetails>
   </soapenv:Body>
</soapenv:Envelope>
```

{% endcode %}

✅ Ensure correct use of namespaces (xmlns) as per the API specification.

***

## Endpoint Details

### Reading Details from the WSDL

The WSDL (Web Services Description Language) file defines:

* Available operations (methods)
* Expected input and output formats
* Required namespaces and endpoints

Use the WSDL to:

* Identify operation names
* Understand the expected structure of requests
* Verify service URLs

📚 In SoapUI, importing the WSDL auto-generates method templates.

***

### Reading Documentation from the XSD

The XSD (XML Schema Definition) describes:

* Data types (string, int, boolean)
* Field validations (e.g., minLength, maxLength)
* Mandatory and optional fields

XSDs are often referenced inside WSDLs and explain how the body structure should be composed.

***

## Testing Requests

### Testing with SoapUI

To read out all the endpoint details of a SOAP API, you can use a tool such as [SoapUI](https://www.soapui.org/downloads/soapui/) (download **SoapUI Open Source**).

1. Create a new SOAP project
   1. Make sure that **Create Requests** is turned on. This way the tool will create sample requests for you with the correct structure, where you simply have to fill in the parameters.

      <figure><img src="https://291121471-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-McrRFZHYH27bqKzOVDd%2Fuploads%2FCVs9abtCWPSnDPlXZpIx%2Fnew%20soap%20project%20modal.jpg?alt=media&#x26;token=f5ffb8df-4e16-4071-8f8b-3697e3addbce" alt=""><figcaption><p>New SOAP Project dialog</p></figcaption></figure>
2. **Import the WSDL**

   Load the WSDL file provided by the API. SoapUI will parse the available methods and message formats.
3. **SoapUI generates available operations**

   All available operations (endpoints) will appear automatically after importing the WSDL
4. **Customize and send requests**

   * Edit the generated XML request templates.
   * Insert the correct field values.
   * Set the SOAPAction manually if needed.

   <figure><img src="https://291121471-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-McrRFZHYH27bqKzOVDd%2Fuploads%2FayTyCu6so16jVhA8Ap6v%2FSOAPAction%20method%20name%20in%20SoapUI.jpg?alt=media&#x26;token=89273b26-ae91-4659-a3e2-b29949fdc7ee" alt=""><figcaption><p>Setting SOAPAction manually inside SoapUI request settings.</p></figcaption></figure>
5. **Review the full XML responses and faults**
   * Inspect the returned XML.
   * Handle successful responses or SOAP faults properly.

Why use SoapUI?

✅ WSDL parsing

✅ Visual method explorer

✅ Automated request templates

***

### Testing with Postman

To test the request in Postman, you can follow this article from Postman itself: [Send SOAP requests](https://learning.postman.com/docs/sending-requests/soap/making-soap-requests/)

* Set method to POST
* Set Headers:

  * Content-Type: `text/xml`
  * SOAPAction (if needed)

  <figure><img src="https://291121471-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-McrRFZHYH27bqKzOVDd%2Fuploads%2FOId8g4vctvNbI8IWsOvD%2Fimage.png?alt=media&#x26;token=d6acbd56-b6d5-4f47-9ea3-5887858d4fb4" alt=""><figcaption><p>Request with Headers in Postman</p></figcaption></figure>
* Paste the XML manually into the raw body
* Send a request and view the response

{% hint style="warning" %}
The `SOAPAction` value always needs to have quotation marks (`""`) around it.
{% endhint %}

{% hint style="info" %}
Postman does not support WSDL parsing.
{% endhint %}

***

### Testing directly inside Locoia

In case the SOAP web service requires the `text/xml` Content-Type, add it as a header to the Connector itself:

```json
{
  "content_type": "text/xml"
}
```

In the actions, you always need to select `post` as the method and add the `SOAPAction` method name in the header.

The XML can be written directly into the request body template.

<figure><img src="https://291121471-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-McrRFZHYH27bqKzOVDd%2Fuploads%2FSQx3ghJvw9cY79ltHtP0%2FCreate%20Connector%20Action%20modal.jpg?alt=media&#x26;token=34edcdac-f6b3-421d-a734-1a1ac5d6476b" alt=""><figcaption><p>Create Connector Action dialog</p></figcaption></figure>

***

## Parsing SOAP Responses

SOAP responses are XML. Extract values using:

* Jinja templating (e.g., regex\_replace)
* Additional Flow steps for XML parsing if needed

Example Jinja Extraction:

```django
{{ body | regex_replace('<id>(.*?)</id>', '\\1') }}
```

***

## Special Notes

* Strict namespace usage is mandatory.
* Handle SOAP faults properly (\<Fault> elements).
* Authentication varies depending on API (Basic Auth, API Key, OAuth).