Introduction

REST to SOAP conversion is a common Forum Sentry use case and is quite easily configured with Sentry's point and click interface. No coding or XSLT is required to enable this conversion.  This article details the steps to configure a Sentry policy that will accept either a SOAP request or a REST call on the same URI for the same remote SOAP API.  Also included is a sample Sentry policy (FSG file) and a SOAPSonar project (SSP file) that can be used to test this Sentry policy.

This tutorial assumes some basic knowledge of the Forum Sentry API Gateway product. This includes building WSDL policies and task lists.

 

Use Case Overview

The policy to be built in this guide will provide a single endpoint that will accept either a SOAP request or a REST GET request with data in the URL query parameters. The Sentry API Gateway will consume either request format, convert if necessary, and then send a SOAP request to the public W3Schools Online Temperature Conversion SOAP API. Depending on the format of the request, Sentry will return to the client either a SOAP response (if a SOAP request) or a JSON response (if a REST request).

 

Sentry Policy Configuration

Note that there are multiple ways to build REST to SOAP conversion policies in Sentry. The correct approach depends on the complexity of the SOAP API, the request formats, etc.  This configuration is an example of a simple REST query string to SOAP and SOAP to JSON conversion. These steps may not be applicable for all SOAP to REST conversion use cases, so if you have difficulties building this for your service, we encourage you to contact Forum Support for specific instructions for your use case.

 

I. WSDL Policy - The first step is to build a WSDL policy for the W3Schools Temperature Conversion web service.  This step will also create the virtual directory and  network policies for this API in Sentry.

1 . On the Gateway>>WSDL Policies page, click New.  Import the WSDL via URL and click next. The URI to the WSDL is below.

http://www.w3schools.com/webservices/tempconvert.asmx?WSDL

 

2. When prompted, build or select your HTTP listener and remote policies for the SOAP 1.1 and SOAP 1.2 ports of this service. Because this WSDL defines both SOAP 1.1 and SOAP 1.2 ports, you essentially go through the same step twice - once for the SOAP 1.1 port and again for the SOAP 1.2 port. 

For the SOAP 1.2 port, you can use the network policies built for SOAP 1.1, but the virtual directory path needs to be changed.

 

This is the WSDL Policy after successful import.

 

3. Modify the HTTP Remote Policy, enabling Response Processing.

 

 

II. Virtual Directory Modifications - For this tutorial we will be focusing on the SOAP 1.1 virtual directory only.

1. While viewing the WSDL Policy, click on the link under the PORT column for the SOAP 1.1 Virtual Directory.  It will bring up the Virtual Directory page.

2. Modify the Filter Expression from the default to a wildcard value of " .* " (that's dot star, without the quotes).

3. Clear the Replace Expression field.

4. Optionally, enable dynamic WSDL retrieval for this Sentry virtual directory with the "Enable WSDL Access" option.

5. Scroll to the bottom and click Save

6. Go back into the Virtual Directory, scroll to the Message Type Filters section at the bottom and click New.

Here you will build a new Message Type filter that will allow Sentry to consume the REST requests. Set the options as displayed in the screen shot below. The Identification Expression is included below for easy copy/paste.

(method == "GET") || (method == "POST") || (method == "PUT") || (method == "DELETE")

7. Create the new Message Type Filter and then Save again on the Virtual Directory.

 

III. Task Lists - Build the appropriate task lists to convert the REST calls to SOAP and convert SOAP responses to JSON format.  There will be a total of 4 task lists built for this use case, 2 for each web service operation (1 for request, 1 for response).  These instructions won't show the full step by step for building the task lists, but instead a general overview.  Simply load the sample policy attached to this tutorial to review the full task lists.

Task List 1 - To convert Celsius to Fahrenheit REST requests to SOAP format.

Task 1: Identify Document - Checks to see if Celsius query parameter exists in the request

Task 2: Maps the Celsius query parameter value to a user attribute

Task 3: Loads a sample Celsius to Fahrenheit SOAP request

Task 4: Maps the Celsius user attribute into the new SOAP message

Task 5: Modifies the HTTP headers and Method for the SOAP API (sets SOAPAction, Content-Type, and changes method to POST)

 

Task List 2 - To convert Celsius to Fahrenheit SOAP responses to JSON format

Task 1: Identify Document - Checks to see if Fahrenheit query parameter exists in the request

Task 2: Converts the SOAP message to XML

Task 3: Converts the XML to JSON

Task 4: Modifies the HTTP response headers - changes the Content-Type to application/json

 

Task List 3 - To convert Fahrenheit to Celsius REST requests to SOAP format.

Task 1: Identify Document - Checks to see if Fahrenheit query parameter exists in the request

Task 2: Maps the Fahrenheit query parameter value to a user attribute

Task 3: Loads a sample Fahrenheit to Celsius SOAP request

Task 4: Maps the Fahrenheit user attribute into the new SOAP message

Task 5: Modifies the HTTP headers and Method for the SOAP API (sets SOAPAction, Content-Type, and changes method to POST)

 

Task List 4 - To convert Fahrenheit to Celsius SOAP responses to JSON format

 Task 1: Identify Document - Checks to see if Celsius query parameter exists in the request

Task 2: Converts the SOAP message to XML

Task 3: Converts the XML to JSON

Task 4: Modifies the HTTP response headers - changes the Content-Type to application/json

 

IV. Task List Groups - This step will consist of building two task list groups, that combine the two request task lists and the 2 response task lists.

1. Create a Task List Group for the request processing.

 

2. Create a Task List Group for the response processing.

 

V. Associate Task List Groups to the WSDL Policy - This is the final step that will enable the REST to SOAP  and SOAP to JSON conversions.

1. Go to the WSDL Policy and click the Settings tab.  Scroll to the PROCESSING SETTINGS near the bottom.

Set the "Pre-process Requests" Task List Group to the request task list group.

Set the "Post-process Responses" Task List Group to the response task list group.

 

Testing the SOAP / REST API

With this single API endpoint in Sentry, you can now send in either a SOAP request or an HTTP GET with query parameter values for temperature conversion. Forum Systems recommends using SOAPSonar for testing of both SOAP and REST APIs. Other SOAP client tools and even browser REST clients should also work.

Sample SOAP Requests

Celsius to Fahrenheit:

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<tns:CelsiusToFahrenheit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:s="http://www.w3.org/2001/XMLSchema" xmlns:tns="http://www.w3schools.com/webservices/">
<tns:Celsius>26</tns:Celsius>
</tns:CelsiusToFahrenheit>
</soap:Body>
</soap:Envelope>

Fahrenheit to Celsius:

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<tns:FahrenheitToCelsius xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:s="http://www.w3.org/2001/XMLSchema" xmlns:tns="http://www.w3schools.com/webservices/">
<tns:Fahrenheit>72</tns:Fahrenheit>
</tns:FahrenheitToCelsius>
</soap:Body>
</soap:Envelope>

 

Sample REST GET URLs

Celsius to Fahrenheit:

http://192.168.82.26:80/webservices/tempconvert.asmx?Celsius=20

Fahrenheit to Celsius:

http://192.168.82.26:80/webservices/tempconvert.asmx?Fahrenheit=80

 

Sample Sentry Policy

Attached is a Sentry FSG file (WSDL policy with all dependencies) that will accept either a SOAP 1.1 call or an HTTP GET request with the correct query parameters for temperature conversion.  It will return either a SOAP response or a JSON response depending on the request.

The import password is simply password.  This will build an HTTP listener on port 80 - which can be changed after the import.

Also attached is a SOAPSonar project file that can be run in SOAPSonar Enterprise Edition and used for testing the attached sample Sentry policy. The only change required is the endpoint URL, which will need to point to your specific Sentry virtual directory.

 

Next Steps

While there are some security parameters already enabled with the default IDP rules (e.g.: schema tightening, virus scanning, payload size, etc.), typically the next steps would include enhancing the security and applying access control.  This includes:

• Enabling SSL with mutual authentication
• Enabling authentication, access control, and/or Single Sign On (SSO)
• Schema tightening for the SOAP messages
• Validation of Query Parameter values for the REST calls
• JSON validation of response documents