Article By: Eunice Mushawatu
SOAP – REST Transformation
Consuming Simple Object Access Protocol (SOAP) APIs is difficult for app developers working with web and mobile applications. Many of the older platforms built on SOAP APIs were not designed for integration via the web or to be consumed the way we use Representational State Transfer (REST) APIs today. While the Layer7 API Gateway is fully capable of publishing SOAP APIs, it is important to consider developer experience as integration use cases evolve. The Layer7 API gateway gives us the ability to expose SOAP APIs as RESTful interfaces. The API gateway creates an abstraction layer to the SOAP service, from the client perspective the API is effectively a REST API. In this article, we explore a use case for SOAP to REST conversion in the Layer7 API gateway.
The Identity Management (IdM) team has requested to expose its ‘create organization’ task as a webservice, the organization has a rule that only REST APIs can be exposed publicly for ease of integration and maintenance. The IdM team has managed to enable webservices for the ‘create organization’ task and is available in the IDM WSDL. The webservice, however, is a SOAP API and in Task Execution Web Services (TEWS) format – Broadcom CA’s webservices core. The ask is to transform the SOAP API into a REST API to allow developers to interact with the API in JSON.
- Symantec Identity Manager must have webservices enabled
- The WSDL for the IdM webservices is available
- Trust relationship between the Layer7 API gateway and Identity Manager has been established
- Must understand XML and XSLT (Extensible Stylesheet Language Transformations)
First, the SOAP service will be published as a REST service on the Layer7 API gateway. The client will send a JSON request to the gateway, which will transform the JSON to XML via policy and use XSLT to modify the XML into the TEWS SOAP format that is required by the backend SOAP API.
The response from the SOAP backend will obviously be in XML, therefore the gateway will have to perform a SOAP to JSON transformation before presenting the response to the client.
Task 1: Get the SOAP Request
So far we have the WSDL definition for the webservices available in Identity Manager. We are specifically interested in the Create Organization task. We will need to use a tool such as SOAP UI to get the individual requests for the Identity Manager tasks. Follow these steps to create a project in SOAP UI and extract the Create Organization request.
- Open SOAP UI and click Project > Add WSDL
- Type in the WSDL URL and click OK. You will be prompted for authentication.
- Open the project you just created and search for the Create Organization task.
- Expand the task and open the request to view the contents. You should see the request structure including all the required and optional parameters in the SOAP request.
- Copy the request and paste it into a txt file. We will use this SOAP request to create a JSON request that will capture all the same parameters.
Task 2: Create the JSON Request
The easiest way to convert the SOAP request to JSON is to use an online convertor such as this free formatter tool. The goal is to have the SOAP request transformed to the following JSON format
Note: This JSON request will be used by the client to send requests to the SOAP endpoint.
Task 3: JSON(REST) to SOAP(XML) Transformation
At this stage we have the JSON request that the client will use. Now it’s time to build the policy that will accept the JSON request and transform it to SOAP and forward it to the backend i.e we want to convert the JSON request to the original SOAP request from task 1 before it can be sent to the backend.
- Create a web API in the gateway as you normally would publish a REST API
- Open the policy window and you may begin drafting the policy for the service.
- As with all services, we will need to first secure the API by enforcing authentication and authorization.
- All other relevant threat protection and input validation assertions should be added here. See example policy below.
- To do the JSON to SOAP transformation, drag and drop the Apply JSON Transformation assertion in the policy.
- Double click the assertion and select ‘JSON to XML’ in the Transformation drop down and specify both the source and target message as ‘Request’.
Task 4: Perform the XSL Transformation
At this stage the request is in XML but it still needs to be transformed into the TEWS format compatible with the backend IdM system. To do this we will leverage XSLT. The XSLT transformation code is written and then saved in the API gateway. We will not go in detail on how the XSLT is written but W3schools.com is an awesome resource and the freeformatter XSLT tool is also a great free resource for testing out your code.
The goal of the XSL transformation is to get the request into the original form that was pulled from the WSDL definition. The input is the newly JSON to XML transformed request, the stylesheet should pull each of the key value pairs and place them in the TEWS XML format. See the sample XSLT stylesheet used for our create organization task below:
|<xsl:stylesheet version=”1.0″ xmlns:xsl=”http://www.w3.org/1999/XSL/Transform”>
<soapenv:Envelope xmlns:ns=”http://www.docusign.net/API/3.0″ xmlns:soapenv=”http://schemas.xmlsoap.org/soap/envelope/” xmlns:wsdl=”http://tews6/wsdl”>
- Drag and drop the Apply XSL Transformation assertion into the policy
- Double click the assertion and select ‘Apply Transformation’ to Request.
- Select Configured in Advance for the ‘Stylesheet Location’.
- Copy and paste the XSLT stylesheet into the space provided and click OK to save.
Task 5: XML to JSON Transformation on the Response
The request can be forwarded to the backend at this point. The last step to complete this SOAP to REST API translation is the response. The response from the backend IdM will be in XML. The response will have to be transformed into JSON before being rendered to the client. Essentially the reverse of what we have already done.
In this example, since a positive response and an error response are structurally different, we separate how the response is processed by response code in policy i.e. 200 vs 500. A positive response only returns a transaction ID which we display as is to the client. A failed transaction returns more details that will need to be extracted, transformed to JSON and then displayed to the client. To extract the required parts of the response we use XPath to match the description/details part of the error. See the example policy snippet below.
The very last assertion translates the XML to JSON just before forwarding response to the client. Notice the Apply JSON Transformation is applied to the Response and not Request.
- Double click the Apply JSON Transformation assertion
- Next to ‘Transformation’ Select XML To JSON from the drop down.
- Select Response for both the Source and Destination
- Click OK to save.
The full policy for this transformation pictured below:
Summary of Exposing a SOAP Service as a RESTful Service
The goal of this article was to provide a scenario that would use the Layer7 API gateway REST-SOAP transformation capabilities in full use. In the use case, we see how to expose a SOAP Identity Manager API and a Restful webservice in the API gateway from start to finish. We discussed how the API is published, how the policy is written to perform the initial REST to SOAP transformation, the XSL transformation as well as the reverse SOAP to REST transformation for the response message to create a full abstraction of the SOAP service. The biggest advantage of using the API gateway for this use case is that no changes are required on the backend service and the developers leveraging this API will not have to handle SOAP and the many different formatting issues that come with legacy services.
Looking for additional help with SOAP and REST API services? ISX Consulting is an elite IAM security firm that offers boundless expertise in a range of cybersecurity and business process services, including API gateways and API management. Take your interoperability to the next level, and contact an ISX consultant today.