Mediation Use Case: SOAP Façade to REST Back-End Service

Learn how to perform mediation by adding a SOAP façade to a REST back-end service, with a specific use case.

In this example, you'll send a SOAP message to a REST back-end service and receive a SOAP response, using mediation in the Akana API Platform, using the FAA Airport Status API.

Table of Contents

• Introduction
• REST to SOAP mediation use case:
  1. Prerequisites
  2. Register the REST service
  3. Create the SOAP façade
  4. Add the process on the SOAP façade to mediate to the REST service
  5. Run the test case
• View a training video

Introduction

In the Community Manager developer portal, you can set up a SOAP façade to a REST back-end service by using the Process Editor to add scripting to a specific operation. When a SOAP message is sent to the back-end service, the process converts it to REST before sending it. The reverse is applied with the response from the REST service. The response is converted back to SOAP format.

There is more than one way to do this. The example in this document uses a script to convert the SOAP message to JSON, retrieve the input parameter, and send a REST message to the back-end service. The response is rendered in XML.

This example uses a simple API, the FAA Airport Status API, which has one operation to retrieve the status of a specific airport, and takes one parameter, a three-letter US airport code. For more information about this service, see https://catalog.data.gov/dataset/airport-status-web-service (external link).

The example walks you through the steps for setting up both APIs, designing the mediation, and running the test case.

REST to SOAP mediation use case

This section provides detailed instructions for setting up and running a REST to SOAP mediation use case using the FAA Airport Status API. This example includes all the assets and steps needed to access a REST back-end service using SOAP messaging, using the Community Manager developer portal.

It includes:

1. Prerequisites
2. Register the REST service
3. Create the SOAP façade
4. Add the process on the SOAP façade to mediate to the REST service
5. Run the test case

Prerequisites

You'll need the following assets, which are included with this document for the FAA Airport Status API, the test case API:

• The Swagger JSON file for the REST API.

  For this example, you can use the Swagger for the FAA Airport Status API.

• A WSDL file for the SOAP façade. This is out of band. You can create the WSDL using a tool of your choice or converting from Swagger or another API description format; the Akana API Platform doesn't do that.

  For this example, a WSDL file for the FAA Airport Status API is included here.

• The script, included inline below. See Mediation script.
• The SOAP request. You could construct it based on your SOAP WSDL file, but it's included in this document so that you can copy and paste. See SOAP request.

Register the REST service

The first step is to set up the API in the Community Manager developer portal. Follow the steps below.

To set up the REST service as an API in the Community Manager developer portal

1. Log in to the API Management Portal.
2. Click the Plus icon to add a new API.
3. Click I have a Swagger/RAML/WSDL/WADL document, and then click File. Click Browse, and navigate to upload the Swagger JSON file for the REST API. See link in Prerequisites above.
4. Test the API in Test Client with a valid airport code (for example, LAX, ATL) to make sure it's up and running.

Create the SOAP façade

Next, set up the SOAP version of the same API. For this, you'd need a WSDL file for the service. For this example, it's provided for you; see link in Prerequisites above.

To set up the SOAP façade as an API in the Community Manager developer portal

1. Log in to the API Management Portal.
2. Click the Plus icon to add a new API.
3. Click I have a Swagger/RAML/WSDL/WADL document, then click File. Click Browse, and navigate to upload the WSDL file. See link in Prerequisites above.
4. Test the API in Test Client with a valid airport code (for example, LAX, ATL). Use the SOAP request message below. It won't work until you add the mediation, because the SOAP message is not understood by the REST back-end service.

SOAP request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:sch="https://soa.smext.faa.gov/asws/schemas">
  <soapenv:Header />
  <soapenv:Body>
    <sch:GET_getAirportStatus_InputMessage>
      <sch:airportCode>LAX</sch:airportCode>
    </sch:GET_getAirportStatus_InputMessage>
  </soapenv:Body>
</soapenv:Envelope>

Add the process on the SOAP façade to mediate to the REST service

The next step is to use the Process Editor to design the REST to SOAP mediation. Essentially you'll:

• Add the process onto the API operation that you're running.
• Add a script that takes the incoming SOAP request and:
  1. Converts the XML to JSON.
  2. Extracts the input parameter and sets it to a variable.
  3. Creates a new message and sends it to the REST API.
  4. Renders the response as a SOAP XML response.
• Define two variables that the process will use.
• Define the output.

To set up the REST to SOAP mediation

1. In the Community Manager developer portal, for the SOAP API, go to Implementations > Live.
2. On the Implementations page, scroll down to the Resources section at the bottom. To the right of the get_getAirportStatus operation, click the down arrow and choose Edit Process. The Process Editor opens.
3. Add a Script Activity to the process by dragging and dropping.

   

4. Double-click in the Script Activity to define the script and:
   1. In the Language drop-down, choose JavaScript
   2. In the Script area, paste the script. See link in Prerequisites above.
   3. Click Finish.
5. Add the script into the process flow. For detailed instructions, see Using the Process Editor.
6. Define the two variables that are used in the script, as follows:
   1. Click the Activity Variables icon:

      

   2. In the Variables and Faults editor, define the variables referenced by the script, as shown below.

      

   3. Click Finish.
7. Modify the Invoke Activity as follows:
   1. Double-click to open it. You'll see that it defaults to invoking the current service, which is the SOAP service.
   2. In the Service QName field, type a part of the REST API name, such as FAA, and click Search.
   3. In the Service field, choose the Target API for the REST service, as shown below.

      

   4. Specify Interface and Operation. In this example, there is only one option for each field.
   5. Click Next.
8. Still in the Invoke Activity wizard—on the Manage Input/Output Parameters page:
   1. In the Input section, choose Multiple Input Variables.
   2. In the Parameters section, the airportCode parameter is displayed. For the variable, choose the airportCode variable that you defined earlier.
   3. In the Output section, for the variable, choose the backendMessage variable that you defined earlier. The page should look like the below.

      

   4. Click Finish.
9. Modify the Reply activity as follows:
   1. Double-click to open it.
   2. In the Variable field, choose the backendMessage variable, as shown below.

      

   3. Click Finish.
10. Save the process changes (fifth icon from the bottom) and then click Finish.

That completes the setup. Now it's showtime! See Run the test case below.

Mediation script

// Get message and normalize
msg = processContext.getVariable("message");
normalmsg = msg.normalize();
auditLog.debug("Normalized message is: " + normalmsg.getContentAsString());
// Create XML2JSON converter
converter= com.soa.json.xml.script.XML2JSON.converter();
converter.setForceTopLevelObject( true );
// optional - use if needed
// converter.setRemoveNamespacePrefixes( true );
// converter.setIgnoreNamespaces( true );
// Convert XML to JSON
var jsonStr = converter.convert(normalmsg.getContentAsString());
auditLog.debug("JSON string is: " + jsonStr);
// Parse JSON string into JSON object
jsonObj = JSON.parse(jsonStr);
// Get airport code 
// An Activity Variable named airportCode needs to be defined
airportCode = jsonObj.GET_getAirportStatus_InputMessage.airportCode;
// Option 1
// In this approach to map to parameters from the backend service
// in the invoke activity
// Set Activity Variable via the processContext to use in the Invoke
processContext.setVariable("airportCode",airportCode);
auditLog.debug("airportCode: " + processContext.getVariable("airportCode"));
// Option 2
// Invoke the backend service without having to map parameters by
// passing the newly created message in to the Invoke
// Create a new normalized message
backendMessage = msgFactory.createNormalized();
backendMessage.createTransportHeaders();
backendMessage.setContentType("application/json");
// Add the airport code as a message part
backendMessage.addPart("airportCode",airportCode);
// Set the Activity Variable with the newly-created message
processContext.setVariable("backendMessage",backendMessage);

Variables referenced by the script

In the Variables and Faults Editor you'll define these two variables:

• airportCode of type string
• backendMessage of type message

Run the test case

Now, you can test by running your SOAP API in Test Client. Previously, when you added the API (see Create the SOAP façade above), you tested the API in Test Client, with a valid airport code, and it didn't work. The back-end REST service couldn't process the SOAP request.

Now, in Test Client, the back-end REST service can process the mediated request. An example is shown below. The request is SOAP; the mediation converts the message to a format the REST back-end service can understand, invokes the REST service, gets the response, and renders it as a SOAP response, in XML.

View a training video

The training video below walks you through all the steps in this use case, using the files referenced here.

• Mediation Use Case: SOAP Façade to REST Back-End Service—video (on this website)

Related Topics