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

Get Started

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

Run Membrane from the command line:

./service-proxy.sh

Warning: If you get an error message on startup you might need to setup a proxy server so the WSDL from the Web Services can be downloaded. See ...

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

<router> 
         
  <soapProxy port="2000"
      wsdl="http://www.thomas-bayer.com/axis2/services/BLZService?wsdl">
  </soapProxy>

  <serviceProxy port="9000">
    <adminConsole /> 
  </serviceProxy> 
        
</router>

Open the URL http://localhost:2000/axis2/services/BLZService in your Web browser. You will see a page describing the Web Service with information from the WSDL:

SOAP Web Service in Admin Console

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>/blz-service</path> to the <soapProxy>:

<soapProxy port="2000" wsdl="http://www.thomas-bayer.com/axis2/services/BLZService?wsdl">
   <path>/blz-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 /blz-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 http://localhost:2000/blz-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="BLZService"> 
   <wsdl:port name="BLZServiceSOAP11port_http" binding="tns:BLZServiceSOAP11Binding"> 
     <soap:address location="http://localhost:2000/blz-service"/> 
   </wsdl:port>
</wsdl:service>

Congratulations! You have already setup an API for a SOAP Web Service! If you are interested in the underlying technologies, you can read more about URL Rewriting in WSDL and XML Schema. (TBD Link!)

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/blz-service?wsdl into the field Initial WSDL and press ÒK.

Expand the SOAP 1.1 binding and double-click Request1.

Fill into the template 37050198 as BLZ. The BLZ is an old routing transit number for German banks.

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 BLZ API. On the Calls-tab, you can inspect HTTP messages that have been exchanged through the API.

Filtering Stacktraces

Now go back to soapUI. We will make the request invalid: Add an element <foo/> to the request.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:blz="http://thomas-bayer.com/blz/"> 
   <soapenv:Header/>
   <soapenv:Body> 
      <blz:getBank>
         <blz:blz>37050198</blz:blz> 
         <foo/>
      </blz:getBank> 
   </soapenv:Body> 
</soapenv:Envelope>

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

Now open proxies.xml and add <soapStackTraceFilter/> as child element of <soapProxy>. The service proxy configuration will now look like this:

<soapProxy port="2000" wsdl="http://www.thomas-bayer.com/axis2/services/BLZService?wsdl">
   <path>/MyBLZService</path> 
   <soapStackTraceFilter />
</soapProxy>

Save the configuration file. Your changes will be picked up by Membrane almost immediately. Go back to soapUI and resubmit your request.

You will note that the backend's stacktrace was removed by the proxy. For security reasons, one should never expose stacktraces in public Web Services. <soapStackTraceFilter/> can help you accomplish that.

SOAP Message Validation against WSDL and XSD Schema

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

<soapProxy port="2000" wsdl="http://www.thomas-bayer.com/axis2/services/BLZService?wsdl">
   <path>/MyBLZService</path> 
   <soapStackTraceFilter/> 
   <validator /> 
</soapProxy>

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: 6; columnNumber: 16; cvc-complex-type.2.4.d: UngxFCltiger Content wurde beginnend mit Element 'foo' gefunden. An dieser Stelle wird kein untergeordnetes Element erwartet.;</detail>
      </soapenv:Fault> 
   </soapenv:Body> 
</soapenv:Envelope>

Go to http://localhost:9000/admin/ and click on BLZService. You will see a visualization of the service proxy for the BLZService. Note that under SOAP Validator you see that 1 out of 1 message has been invalid. These numbers count (invalid) messages since startup or the last configuration change.

Have a look at the examples there you will find more how to use Membrane for SOAP and Web Services.