SOAP Web Services using MuleSoft

In the real word, we prone to use REST style of architecture to describe the rules and standards for interactions with an API, making it easy, scalable, efficient and modular. At the same time, lots of systems and enterprise applications such as ERP, CRM, and especially legacy, complex, and highly secure will remain using SOAP in the nearest future. That is why it is crucial to understand and leverage the opportunities that MuleSoft provides to easily create these types of services.

Going ahead, we will talk about creation of a SOAP-based MuleSoft API.

Key points of SOAP-based MuleSoft APIs:

1. Web Services Description Language (WSDL) is an XML notation for describing and documenting SOAP API interfaces
2. Accelerated development based on MuleSoft’s APIkit for SOAP
3. Creating a SOAP-based MuleSoft API involves using Anypoint Studio, or Anypoint Code Builder

Let’s go and dive deeper following this step-by-step guide, using Anypoint Studio to create a MuleSoft API that exposes a SOAP-based web service.

Steps to create a SOAP-based MuleSoft API:

1. Create or reuse a WSDL file
2. Create a SOAP-based MuleSoft API from Anypoint Studio
3. Add flow implementation
4. Configure SOAP APIKit router
5. Deploy and run

WSDL file

In our example, we’re going to use a simplified example of WSDL file defines a BMI (Body Mass Index) calculator service, with one operation to calculate adult’s BMI.

<?xml version="1.0" encoding="UTF-8"?>
<wsdl:definitions xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
                  xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
                  targetNamespace="http://mulesoft.org/calculator"
                  xmlns="http://mulesoft.org/calculator">

    <!-- Types section defines data types -->
    <wsdl:types>
        <xs:schema targetNamespace="http://mulesoft.org/calculator"
                   xmlns:xs="http://www.w3.org/2001/XMLSchema">
            <xs:element name="CalculateAdultBMIRequest">
                <xs:complexType>
                    <xs:sequence>
                        <xs:element name="weight" minOccurs="1" type="xs:double" nillable="false"/>
                        <xs:element name="height" minOccurs="1" type="xs:double" nillable="false"/>
                    </xs:sequence>
                </xs:complexType>
            </xs:element>
            <xs:element name="CalculateAdultBMIResponse">
                <xs:complexType>
                    <xs:sequence>
                        <xs:element name="bmi" type="xs:double"/>
                        <xs:element name="category" type="xs:string"/>
                    </xs:sequence>
                </xs:complexType>
            </xs:element>
        </xs:schema>
    </wsdl:types>

    <!-- Message elements define the structure of messages -->
    <wsdl:message name="CalculateAdultBMIInputMessage">
        <wsdl:part name="parameters" element="CalculateAdultBMIRequest"/>
    </wsdl:message>
    <wsdl:message name="CalculateAdultBMIOutputMessage">
        <wsdl:part name="parameters" element="CalculateAdultBMIResponse"/>
    </wsdl:message>

    <!-- Port Type describes operations -->
    <wsdl:portType name="AdultBMICalculatorPortType">
        <wsdl:operation name="CalculateAdultBMI">
            <wsdl:input message="CalculateAdultBMIInputMessage"/>
            <wsdl:output message="CalculateAdultBMIOutputMessage"/>
        </wsdl:operation>
    </wsdl:portType>

    <!-- Binding specifies protocol and message format -->
    <wsdl:binding name="AdultBMICalculatorSoapBinding" type="AdultBMICalculatorPortType">
        <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>
        <wsdl:operation name="CalculateAdultBMI">
            <soap:operation soapAction="http://mulesoft.org/calculator/CalculateAdultBMI"/>
            <wsdl:input>
                <soap:body use="literal"/>
            </wsdl:input>
            <wsdl:output>
                <soap:body use="literal"/>
            </wsdl:output>
        </wsdl:operation>
    </wsdl:binding>

    <!-- Service describes the endpoint -->
    <wsdl:service name="BMIService">
        <wsdl:port name="CalculatorSoap" binding="AdultBMICalculatorSoapBinding">
            <soap:address location="http://localhost:8081/calculator"/>
        </wsdl:port>
    </wsdl:service>
</wsdl:definitions>

Now, we are ready to start working on the web service Mule API.

SOAP-based MuleSoft API from Anypoint Studio

We start by creating a project in Anypoint Studio:

1. Go to File -> New -> Mule Project
2. Set project name to bmi-calculator-api
3. In section API Implementation choose:
   Import RAML from local file -> Add Location of the WDL file
4. Press Finish

Automatically, Anypoint Studio will generate the following flows:

1. api-main — Main flow with listener and SOAP Router
2. CalculateAdultBMI — Flow automatically generated based on WSDL operation name. If the SOAP Service has more operations, then the same quantity of flows with same operation names will be created

Flow Implementation

It’s time to start implementing the CalculateAdultBMI flow.

To calculate adult’s BMI we will be measure by using weight in kilograms (kg) divided by the square of height in meters (m2) to estimate the amount of body fat adult has.

Thus, we expect request body to have 2 fields, weight and height:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:bmi="http://mulesoft.org/calculator">
   <soapenv:Header/>
   <soapenv:Body>
      <bmi:CalculateAdultBMIRequest>
         <weight>?</weight>
         <height>?</height>
      </bmi:CalculateAdultBMIRequest>
   </soapenv:Body>
</soapenv:Envelope>

Weight and height are mandatory fields and could not be NULL based on the rules defined in the WSDL file.

Response body is going to be constructed of:

• bmi — index based on calculation
• category — category of the excessive body fat according to WHO organization categorization

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
    <soapenv:Body>
        <CalculateAdultBMIResponse>
            <bmi>?</bmi>
            <category>?</category>
        </CalculateAdultBMIResponse>
    </soapenv:Body>
</soapenv:Envelope>

Now, when we are clear with all the requirements, we can easily create a server-side logic and define the implementation steps:

1. Add Set variable component from Mule Palette to obtain the request body values to easily access them from the next step
2. Add Transform message component from Mule Palette to calculate BMI and to identify the category based on BMI number using DataWeave language

The final flow implementation:

Configure SOAP APIKit router

SOAP APIKit router is the component responsible for routing requests to the appropriate Mule flows, based on the SOAP operations and endpoints.

APIKit for SOAP Configuration is a global property used to configure SOAP router. Within the SOAP Configuration we can define:

1. SOAP version — currently available 11 and 12 versions
2. SOAP address — address of the web service
3. Inbound validation enabled — checkmark to validate request against WSDL file
4. Namespace prefixes — key-value pairs to be added to the response
5. Connection details — WSDL location, service and port

In our example, we have enabled inbound validation to validate presence of mandatory fields weight and height inside the request, added namespace prefix and set connection with WSDL file.

We have all set and ready to deploy, run and test our service.

Deploy and run

Deploy your MuleSoft application, and it will expose the SOAP-based BMI calculator service using the WSDL for the CalculateAdultBMI operation. Clients can now consume the service.

Let’s check if request validation from SOAP APIKit works as expected by sending an invalid payload, without required height element:

Response came back with a schema validation error, stating that height element is mandatory.

We reached the goal 😎

Photo by James Orr on Unsplash

Thank you for reading!

Links to the code and additional resources could be found below:

1. Build a MuleSoft API — https://docs.mulesoft.com/mule-runtime/4.5/build-application-from-api
2. APIKit for SOAP — https://docs.mulesoft.com/apikit/4.x/apikit-4-for-soap
3. DataWeave match() function — https://docs.mulesoft.com/dataweave/2.5/dataweave-pattern-matching
4. DataWeave POW() function — https://docs.mulesoft.com/dataweave/2.5/dw-core-functions-pow
5. Git repo — https://github.com/tarantsovakseniya/bmi-calculator-api