Ballerina SOAP Connector

In today’s world, the trend is writing and exposing services in a simple and lightweight manner. So REST over HTTP is almost always the basis for modern microservices development and communications.

But still, there is a considerable amount of APIS that support SOAP and SOAP has unique security features that can come in handy in APIs that need high security (ex: Bank applications). So in Ballerina, we have a SOAP client connector which can be used to communicate with SOAP backends. It supports both SOAP 1.1 and SOAP 1.2 versions.

SOAP connector allows you to send an XML request to a SOAP backend by specifying the necessary details to construct a SOAP envelope. It basically abstracts out the details of the SOAP envelope like headers, WS-addressing, WS-security into simple configuration fields and internally creates the whole SOAP envelope and call the specified SOAP backend.

First of all, I will go through the functions of the SOAP client connector.

1. sendReceive
Sends request and expects a response.

2. sendRobust
Sends the request and possibly receives a response if there is an error.

3. fireAndForget
Sends the request without the possibility of any response from the service(even an error).

Let’s start a SOAP backend

If you have a WSO2 EI downloaded in your computer, go to <EI_HOME>/samples/axis2Server/src/SimpleStockQuoteService
And run ‘ant’ to build the service.
Then go to
<EI_HOME>/samples/axis2Server
and run the axis2 server.
You can refer this for more information.

Let’s create a Ballerina SOAP client

Soap11Client soapClient = new("http://localhost:9000");

Above creates a SOAP client for connecting to a SOAP 1.1 backend. If you want to connect to a SOAP 1.2 backend, you can create it as follows,

Soap12Client soapClient = new("http://localhost:9000");

Sample code for connecting to a SOAP 1.1 backend. Here I have used the sendReceive function as an example. For the sendRobust, fireAndForget also this is similar.

import ballerina/io;
import wso2/soap;
import ballerina/http;

public function main() {
    soap:Soap11Client soapClient = new("http://localhost:9000/services");
    xml body = xml `<m0:getQuote xmlns:m0="http://services.samples">
                        <m0:request>
                            <m0:symbol>WSO2</m0:symbol>
                        </m0:request>
                    </m0:getQuote>`;

    var resp = soapClient->sendReceive("/SimpleStockQuoteService", "urn:getQuote", body);
    if (resp is soap:SoapResponse) {
        io:println(resp);
    } else {
        io:println(resp.detail().message);
    }
}

By running the above code you can get a response as follows,

{soapVersion:"SOAP11", headers:[], payload:<ns:getQuoteResponse xmlns:ns="http://services.samples"><ns:return xmlns:ax21="http://services.samples/xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="ax21:GetQuoteResponse"><ax21:change>-2.600514169064172</ax21:change><ax21:earnings>13.640744219736426</ax21:earnings><ax21:high>-79.12330090673208</ax21:high><ax21:last>80.4140599008811</ax21:last><ax21:lastTradeTimestamp>Wed Apr 03 17:27:26 IST 2019</ax21:lastTradeTimestamp><ax21:low>-80.36988253322528</ax21:low><ax21:marketCap>3.698155786628981E7</ax21:marketCap><ax21:name>WSO2 Company</ax21:name><ax21:open>84.02990986584717</ax21:open><ax21:peRatio>24.1953880571607</ax21:peRatio><ax21:percentageChange>-2.8151815157798326</ax21:percentageChange><ax21:prevClose>92.37465344552763</ax21:prevClose><ax21:symbol>WSO2</ax21:symbol><ax21:volume>7831</ax21:volume></ns:return></ns:getQuoteResponse>}

Please note that when you are creating a SOAP 1.1 client, it is mandatory to pass the soapAction (“urn:getQuote” in the above example) to the sendReceive remote function. But it is not mandatory to pass the soapAction in SOAP 1.2 requests. You just need to pass the body.
For EX:

var resp = soapClient->sendReceive("/SimpleStockQuoteService",body);