SOAP Web Services Tutorial

In this tutorial you will learn how to use Membrane as an API Gateway for SOAP based Web Services. We will setup an API and add the following features:

API configuration from WSDL
Validation of SOAP requests and responses against a WSDL document
Rewriting the path for the Web Service

Getting Started

Download Membrane API Gateway, unzip it and go to the extracted folder tutorials/soap.

Run Membrane from the command line:

./service-proxy.sh

Open proxies.xml and have a look at the configuration you just started:

<router>

        <soapProxy port="2000"
                   wsdl="https://www.predic8.de/city-service?wsdl">
        </soapProxy>

        <api port="9000">
            <adminConsole />
        </api>

</router>

Open the URL localhost:2000/city-service in your Web browser. You will see a page describing the Web Service with information from the WSDL:

SOAP Web Service

Note that the name, path and target endpoint are extracted from the WSDL. The WSDL was retrieved at startup from the location specified in the configuration file.

Now go back to the configuration file and add <path>/soap-service</path> to the <soapProxy>:

<soapProxy port="2000" wsdl="https://www.predic8.de/city-service?wsdl">
   <path>/soap-service</path>
</soapProxy>

Save the configuration file. The changes will be picked up by Membrane almost immediately.

The change will make the service available under the path /soap-service instead of the path that was extracted from the WSDL. Reload the description at its new location (the old one will, not work anymore) at localhost:2000/soap-service.

Click on the link to the WSDL. Note that the endpoint URL at the very bottom has automatically been changed by Membrane. This causes SOAP requests from the client to be passed through the API.

<wsdl:service name="CityService">
   <wsdl:port name="CityPort" binding="tns:CitySoapBinding">
     <soap:address location="http://localhost:2000/soap-service"/>
   </wsdl:port>
</wsdl:service>

Congratulations! You have already setup an API for a SOAP Web Service!

Send a SOAP Request trough the API

Now we will use soapUI as a SOAP client. Install and start soapUI.

To create a new project click on File/New SOAP Project. In the dialog just paste the WSDL address http://localhost:2000/soap-service?wsdl into the field Initial WSDL and press OK.

Expand the getCity binding and double-click Request 1.

In the <name>tag , replace the placeholder ? with the city name London

Submit the request by clicking the green arrow. You will observe a successfully proxied SOAP response. Click on XMLon the left to beautify the XML.

Now go to http://localhost:9000/admin/. You will see the CityService API. On the Calls-tab, you can inspect HTTP messages that have been exchanged through the API.

SOAP Message Validation against WSDL and XSD Schema

Go back to soapUI. We will make the request invalid by changing the <name> element to <foo>.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:cit="https://predic8.de/cities">
    <soapenv:Header/>
    <soapenv:Body>
        <cit:getCity>
            <foo>London</foo>
        </cit:getCity>
    </soapenv:Body>
</soapenv:Envelope>

Resubmit the request by clicking the green arrow again. Observe the exception from the backend:

Now add <validator /> as another child element of <soapProxy> in the configuration and save it.

<soapProxy port="2000" wsdl="https://www.predic8.de/city-service?wsdl">
   <path>/soap-service</path>
   <validator /> 
</soapProxy>

Resubmit the request. Membrane will now perform WSDL and XSD Schema validation on all requests and responses for this service. Your invalid request will not be forwarded to the server. Instead you can observe this validation error:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
    <soapenv:Body>
        <soapenv:Fault>
            <faultcode>soapenv:Server</faultcode>
            <faultstring>Message validation failed!</faultstring>
            <detail>Validation failed: org.xml.sax.SAXParseException; lineNumber: 5; columnNumber: 15; cvc-complex-type.2.4.a: Invalid content was found starting with element 'foo'. One of '{name}' is expected.; </detail>
        </soapenv:Fault>
    </soapenv:Body>
</soapenv:Envelope>

Go to http://localhost:9000/admin/ and click on CityService. You will see a visualization of the service proxy for the CityService. Expand the description of the SOAP Validator by clicking on the three points .... Note that 1 out of 1 message has been invalid according to the specified WSDL. These numbers count (invalid) messages since startup or the last configuration change.

Have a look at the examples to find more short tutorials on how to use Membrane for SOAP and Web Services.