Transform Existing SOAP Based Web Service To REST Based API Using Azure API Management

Prerequisites

• Azure account
• Azure API Management resource.

Step 1

Login to your Azure account.

Step 2

Click + icon to add new resource and search for API Management.

 

Step 3

Click API Management icon, which will take you to API Management creation process.

Step 4

Enter the appropriate details in the below form and click Create button. It will create Azure API Management interface through which you can manage your API. Now, we will use this newly created API Management to transform the SOAP backend to REST API.

Step 5

Go to the newly created API Management resource screen and click Publisher portal.

Step 6

In the Publisher portal, click Import API.

Step 7

Select WSDL as Specification Format and enter SOAP link in Specification Document URL and enter the appropriate details, as shown below and click Save. 

Note

I have used an open source SOAP Service for the explanation.

Step 8

If the WSDL has multiple end points, the screen given below will appear. Among multiple items, we are able to choose only one. Choose "OrdersAPI::basic and click Select button.

Now, you will see the screen given below with SOAP based Web Service Orders API, which has been imported to Azure API Management , as shown below.

 

Now API Management will transform SOAP backend to REST API.

During the import process, Azure API Management will generate the special policies to the inbound transform from JSON to a SOAP and the same thing will happen on the outbound flow.

Step 9

Click Operation to view the API definition and you can see in the screen given below that Orders API are now transformed to REST API structure. The structure of Orders Service shows the image given below. We will use this structure to discuss about the further transform process.

Step 10

Click GetOpenOrders and you can see it is having REST API structure with the http verbs. Here, the request is provided to REST based GetOrders. In the background, the request transfers to Rewrite URL template, which holds SOAP Service reference.

Step 11

Click Policies to view in more detail about the background process.

Under API dropdown, select OrdersAPI, Operation as GetOrders and click Configure Policy.

Proceed with the code, as shown below.

<policies>
    <inbound>
        <base />
        <rewrite-uri template="/FazioService.svc" copy-unmatched-params="false" />
        <set-header name="SOAPAction" exists-action="override">
            <value>"http://tempuri.org/IFazioService/GetOrder"</value>
        </set-header>
        <set-body template="liquid">
            <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns="http://tempuri.org/">
                <soap:Body>
                    <GetOrder>
                        <orderId>{{body.getOrder.orderId}}</orderId>
                    </GetOrder>
                </soap:Body>
            </soap:Envelope>
        </set-body>
        <set-header name="Content-Type" exists-action="override">
            <value>text/xml</value>
        </set-header>
    </inbound>
    <backend>
        <base />
    </backend>
    <outbound>
        <base />
        <choose>
            <when condition="@(context.Response.StatusCode < 400)">
                <set-body template="liquid">
                                                    {
  "getOrderResponse" :
  {
    "getOrderResult" :
    {
      "customer_id" : {{body.envelope.body.GetOrderResponse.GetOrderResult.customer_id}},
      "line_items" :
      [
        {% JSONArrayFor item in body.envelope.body.GetOrderResponse.GetOrderResult.line_items-%}
{{item}}
        {% endJSONArrayFor -%}
      ]
,
      "order_header_data" :
      {
        "bar" : {{body.envelope.body.GetOrderResponse.GetOrderResult.order_header_data.Bar}},
        "foo" : "{{body.envelope.body.GetOrderResponse.GetOrderResult.order_header_data.Foo}}"
      },
      "order_id" : {{body.envelope.body.GetOrderResponse.GetOrderResult.order_id}},
      "shipping_address" :
      {
        "address1" : "{{body.envelope.body.GetOrderResponse.GetOrderResult.shipping_address.Address1}}",
        "address2" : "{{body.envelope.body.GetOrderResponse.GetOrderResult.shipping_address.Address2}}",
        "city" : "{{body.envelope.body.GetOrderResponse.GetOrderResult.shipping_address.City}}",
        "country" : "{{body.envelope.body.GetOrderResponse.GetOrderResult.shipping_address.Country}}",
        "stateCounty" : "{{body.envelope.body.GetOrderResponse.GetOrderResult.shipping_address.StateCounty}}",
        "zipPostcode" : "{{body.envelope.body.GetOrderResponse.GetOrderResult.shipping_address.ZipPostcode}}"
      }
    }
  }
}

                                        </set-body>
            </when>
            <otherwise>
                <!-- Error response as per https://github.com/Microsoft/api-guidelines/blob/master/Guidelines.md#7102-error-condition-responses  -->
                <set-body template="liquid">
                                        {
                                        "error": {
                                            "code": "{{body.envelope.body.fault.faultcode}}",
                                              "message": "{{body.envelope.body.fault.faultstring}}"
                                              }
                                        }
                                    </set-body>
            </otherwise>
        </choose>
        <set-header name="Content-Type" exists-action="override">
            <value>application/json</value>
        </set-header>
    </outbound>
</policies>

Look at <set-body> tag, which refers to the liquid template. It holds SOAP structure and transforms it into REST response.

In the screen given below, you can see JSON response template, which has been rendered as JSON from SOAP body XML. It ensures that REST API returns JSON response to your frontend.

Proceed with the code given below.

<set-body template="liquid">
                                                    {
  "getOrderResponse" :
  {
    "getOrderResult" :
    {
      "customer_id" : {{body.envelope.body.GetOrderResponse.GetOrderResult.customer_id}},
      "line_items" :
      [
        {% JSONArrayFor item in body.envelope.body.GetOrderResponse.GetOrderResult.line_items-%}
{{item}}
        {% endJSONArrayFor -%}
      ]
,
      "order_header_data" :
      {
        "bar" : {{body.envelope.body.GetOrderResponse.GetOrderResult.order_header_data.Bar}},
        "foo" : "{{body.envelope.body.GetOrderResponse.GetOrderResult.order_header_data.Foo}}"
      },
      "order_id" : {{body.envelope.body.GetOrderResponse.GetOrderResult.order_id}},
      "shipping_address" :
      {
        "address1" : "{{body.envelope.body.GetOrderResponse.GetOrderResult.shipping_address.Address1}}",
        "address2" : "{{body.envelope.body.GetOrderResponse.GetOrderResult.shipping_address.Address2}}",
        "city" : "{{body.envelope.body.GetOrderResponse.GetOrderResult.shipping_address.City}}",
        "country" : "{{body.envelope.body.GetOrderResponse.GetOrderResult.shipping_address.Country}}",
        "stateCounty" : "{{body.envelope.body.GetOrderResponse.GetOrderResult.shipping_address.StateCounty}}",
        "zipPostcode" : "{{body.envelope.body.GetOrderResponse.GetOrderResult.shipping_address.ZipPostcode}}"
      }
    }
  }
}

                                        </set-body>

You can click the Cancel button now. Let us view REST API behavior in the developer portal.

Step 12

Go to API management overview and click Developer portal.

Step 13

In the developer portal, go to Orders API. Use the developer console to see a RESTful payload is coming back to you from SOAP API.

Click GetOpenOrders, hit Try It button and you will be presented with an example request. 

In the request body JSON, enter the appropriate request JSON message and click Try it.

 

Now, you can see the JSON response below, which has the response message with the response latency details.

You can also explore the overall execution process under the Trace tab.

Conclusion

As Azure API Management offering is frequently getting loaded with back to back new features, the SOAP to REST transformation feature is a great addition to Azure API Management and this feature is very user friendly. The developer can expose his existing SOAP Service as REST API without much effort.