Converting SOAP to REST - Customizing the request/response messages generated by the REST2SOAP wizard

[#1]

If you are using the wizard (in Management UI) to convert you SOAP/WSDL to REST API, the wizard does a pretty good job of guessing the right resource names and verbs for your corresponding SOAP Methods. However, if you want to customize how you go about doing it, here are the steps.

The reasons for customizing could be because the wizard is not generating the messages properly or could be because you are not comfortable sending certain data as query param or could be anything else.

To begin with, there is a basic level of customization you can do at the wizard level. I strongly recommend you do them, even if you are building demos/prototypes, and make your API more RESTful:

1. Make sure you add a version number to your API Basepath. I would prefer to start from V2, as usually V1 is associated to the actual SOAP service, in the minds of the people
2. Update the resource names if necessary. I have seen cases where the SOAP Methods are unusually long and confusing. You don’t want to inherit those sins into your API
3. Uncheck the methods that are not necessary for your API

It’s pretty straightforward so far, and now lets move on to what happens after you click that magic button ‘build’. The UI generates policies automatically that would do the required translations. There is nothing extraordinary about these policies. They are standard AssignMessage, ExtractVariables policies. But they have been auto configured for an extra bit of convenience.

In this article, I will walk you through how you can customize the request message, but the process is pretty similar for the response messages as well.

There are two policies that are of particular interest.

1. {Resource name} Extract Query Param – This policy extracts the params that your SOAP payload will need. You will see this policy for only those methods that have payload elements in the SOAP Body.

This is the policy you will change if you want to extract the request param from a header for example, instead of query params. However based, on the usecases- you might sometimes have to extract these from API BaaS or do some custom javascript coding, as opposed to extracting them from the request itself. The important thing to note is the variable name, because it is what is referred in the subsequent policy.

Your policy will have a code that might look like this:

<Pattern ignoreCase="true">{ZIP}</Pattern>

In this case the variable ‘ZIP’ is the one that matters. You can populate it however you want, as long you are doing it before the execution of the 2^nd important policy, I am going to talk about now.

2. {Resource Name} Build SOAP – This policy is the one that is constructing the SOAP payload. If, for what ever reason, the request message is not liked by your backend service, this is the policy you will have to edit.

For the most part, you will update the SET the Payload section. In some cases, if you have to update the SOAP Action or other headers.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<AssignMessage async="false" continueOnError="true" enabled="true" name="GetCityForecastByZIP-build-soap">
...
    <Add>
        <Headers>
            <Header name="SOAPAction">...</Header>
        </Headers>
    </Add>
    <Set>
        <Headers>
            <Header name="Content-Type">text/xml; charset=utf-8</Header>
        </Headers>
        <Payload contentType="text/xml">
            <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
                <soap:Body>
                    <GetCityForecastByZIP xmlns="http://ws.cdyne.com/WeatherWS/">
                        <!--Optional-->
                        <ZIP>{ZIP}</ZIP>
                    </GetCityForecastByZIP>
                </soap:Body>
            </soap:Envelope>
        </Payload>
        <Verb>POST</Verb>
    </Set>
    <AssignVariable>
        <Name>forward.target.url</Name>
        <Value>http://wsf.cdyne.com/WeatherWS/Weather.asmx</Value>
    </AssignVariable>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
    <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

The best way to debug this policy against the actual request to your SOAP service, that works (from SOAP UI or other client). If you are using SOAP UI but make sure to check the ‘RAW’ tab, to see all the headers that it is sending.

These are the 2 most common polices that will help you get your REST2SOAP working.