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
Download Membrane API Gateway, unzip it and go to the extracted folder
Run Membrane from the command line:
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 ...
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:
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 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
SOAP 1.1 binding and double-click
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.
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:
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
<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.