A few months ago we added SOAP pass-through support to Azure API Management – thank you to all of you using and giving us feedback on this feature. One of the top requests was, “How can I transform my SOAP backend into a RESTful HTTP front end?” This blog posts will walk you through how to use this new feature.

Let's get started! We will need a WSDL file that we will import – while SOAP to REST conversion can be done manually using policies, the easiest way is to use our WSDL import facility, and then customize as you require. Either retrieve the URL of the WSDL of your SOAP service that you would like to use, or use our example Orders SOAP Service. A few things to make you aware of in how we support WSDLs:

• We support SOAP services defined using WS-I Basic Profile 1.1, SOAP 1.1, WSDL1.1 and SOAP 1.2.
• We do not currently support WSDLs containing the elements wsdl:import, or messages with multiple parts

In the publisher portal, browse to the APIs menu and select “Import API”. On the screen that appears, you can now choose from WADL, Swagger or WSDL as your Import format.

Select WSDL, and then either paste link or browse to your WSDL file. You will then need to choose what type of WSDL import you are doing – choose “SOAP to REST” – Give your API a URL suffix (e.g. “Orders”), and add it to a product if you wish (we will be adding our example to a product so that we can test it in the developer portal). Select 'Save'.

The next screen that may appear, and that appears here in our demo, is one that occurs when your WSDL file has multiple service endpoints defined (“Port Types” or “Interfaces”). In order for us to treat our SOAP API in a similar manner to other APIs, we need to import only one of the interfaces defined within it (the other interfaces can be imported as separate APIs). Select FazioService::basic to continue.

API Management will now create your SOAP to REST API. This is where the difference with a SOAP Pass-through API occurs. When you browse the API menu and look at the definition of operations, you will see normal REST definitions – what will be different however is that the Rewrite URL template field will be pointing to your backend SOAP service.

So what are we doing to accomplish this? As part of the import process, Azure API Management is generating special policies that to the inbound transform from JSON to a SOAP envelope, and vice versa on the outbound flow. We are using an updated version of the set-body policy that allows the use of Liquid templates. Let's take a close look at these.

Templates

We now allow you to use a Liquid template in the set-body policy. This template can be used to complete transform the body of a request or response in any way you see fit – we are using it specifically here for SAOP to REST but the policy is not limited to that. For more information about Liquid, take a look at the Liquid introduction. The policy in GetOrders shows a simple example of how the Liquid template works (notice the use of {{body.getOrder.orderId}} to inject values from the JSON body into the template):

{{body.getOrder.orderId}}

You will see if you look at the policy that has been created, that the outbound policy that has been created is very different to the inbound. This because we are transforming SOAP back into JSON. We are also checking the response that comes back from the SOAP API – if we receive a HTTP status code greater than 400, we will take a look at the SOAP fault and forward on an error message.

The great thing about using templates for SOAP to REST is that once we have done the initial import and setup for you, you are free to make changes modify and tailor to your needs.

In the Developer Portal, if you click on Orders API, you can now see the operations and documentation we have generated. Use the developer console to see a RESTful payload coming back from you SOAP API. Click on “GetOpenOrders”, hit the “Try It” button, and you will be presented with an example request. For GetOpenOrders, change the customer number (the “cust” value) to “1001” to retrieve an example response. If you are logged on as administrator, take a look at the “Trace” tab – you can have a look at how quickly the template execution has occurred.

API

If you wish, you can also perform a SOAP to REST import using our own management API:

https://.management.current.azure-api.net/apis/soapapi?import=true&path=soapapi&apiType=Http&api-version=2014-02-14-preview

apiType should be set to “Http” for SOAP to REST, “Soap” for SOAP pass-through.