Author: Rizwan, Mohammed
Supported Versions: 10.0 & above
Introduction
This tutorial will help the users to understand the functionality of SOAP-to-REST transformation and how to use it in API Gateway.
Feature Description
SOAP web services are commonly used to expose data within enterprises. With the rapid adoption of the REST APIs, it is now a necessity for API providers to have the ability to provide RESTful interfaces to their existing SOAP web services instead of creating new REST APIs. Using the API Gateway SOAP to REST transformation feature, the API provider can either expose the parts of the SOAP API or expose the complete SOAP API with RESTful interface. API Gateway allows you to customize the way the SOAP operations are exposed as REST resources. Additionally, the Swagger or RAML definitions can be generated for these REST interfaces.
Requirement
API Provider wants to expose all or some of the operations from the existing SOAP service as a REST service instead of creating new REST APIs.
Prerequisites
SOAP API should be created in the API Gateway.Capabilities
- API Gateway allows to enable SOAP API in a RESTful way to its clients and disabled it by default.
- The API Provider can enable all or some operations of an SOAP API to be exposed as REST to the users.
- After enabling, the SOAP Operation is ready to be invoked in a RESTful way with default values.
- The API Provider can configure custom values for the resource paths and the methods.
- The API Provider can also modify the default request/response schemas and examples that are generated.
- API Gateway handles the SOAP API attachments by using multipart/form-data or multipart/mixed content-types
Below screenshot shows the sample soap operation and its equivalent REST resource.
Steps to enable REST transformation
- Go to API details page
- Edit the API
- Click 'Rest transformation'
- Use the toggle button next to 'Transform all operations' to transforming all the operations.
- Use the toggle button next to each operation to transform the specific operation.
Default values
API Gateway allows the API Provider to select the operations from the created SOAP API to transform it to REST resources. REST resource is created with the below attributes.
| Artribute Name | Description |
| Resource Name | Name of the operation |
| Resource Path | /{Name of the operation} |
| HTTP Method | POST |
| Example of the input request for content-type application/json and application/xml | Json and xml sample are derived from the input message of the operation |
| Example of the output response for content-type application/json and application/xml | Json and xml sample are derived from the output message of the operation |
Below is the screenshot of the UI to show the default value when enabling the operation to expose it as a REST resource
API Gateway also provides the flexibility to modify the REST resource attribute values. API Provider can modify the resource name, resource path, method, sample for request and response. He can also add a new parameter, content-type based request, response and content-type based schema and sample under the response.
API Gateway provides way to transforming all the operations in a single toggle button or transform selective operations.
Employee Service
Let's take employee service as an example to understand this feature better. Link to the input file EmployeeService.wsdl used for creating this SOAP API. Employee service has 5 soap operations to support CRUD operations. Let's transform all the operations into a proper REST service by adding/modifying the attributes like method, parameters, etc. The below table contains existing SOAP operations with their equivalent REST resource, method and parameter type.
| SOAP Operation | REST Resource | Method | Parameter |
| createEmp | /employee | POST | Body parameter |
| updateEmp | /employee/{id} | PUT | Body, query parameter |
| deleteEmp | /employee/{id} | DELETE | Query parameter |
| getEmp | /employee/{id} | GET | Query parameter |
| getAllEmployees | /employee | GET | NA |
Use case 1 - Create employee
Expand the createEmp soap operation and change the resource path as '/employee'. No change is required for 'method' as it is POST by default.
Use case 2 - List all employees
Expand the getAllEmployees soap operation and change the resource path as '/employees', method as GET. As GET operation does not require the input request, both the content-type-based body parameter was removed.
Use case 3 - Read employee
Expand the getEmp soap operation and change the resource path as '/employee/{id}', method as GET. As GET operation does not require the input request, both the content-type based body parameter were removed. New path parameter 'id' is added where the type is a string, required is true and XPath is //employeeId.
Path parameters in a resource path and query parameters in the request need to be mapped to the SOAP element in request to be sent to the Native service using Xpaths.
Setting the xpath is to link the employeeId in the REST resource with the employeeId field in the input request of the getEmp. Below is the sample input request of getEmp.
Use case 4 - Update employee
Expand the updateEmp soap operation and change the resource path as '/employee/{id}', method as PUT. New path parameter 'id' is added where the type is a string, required is true and xpath is //employeeId
Use case 5 - Delete employee
Expand the deleteEmp soap operation and change the resource path as '/employee/{id}', method as DELETE. As the DELETE operation does not require the input request, both the content-type based body parameter was removed. New path parameter 'id' is added where the type is a string, required is true and xpath is //employeeId.
REST Resource Runtime Invocation
A SOAP API that is exposed in API Gateway would usually mediate the SOAP request that the clients send to the Native API. When the provider wants to expose the same SOAP API for Mobile applications sending JSON requests, API Gateway takes the responsibility to convert this RESTful request into SOAP form such that this request can be forwarded to the Native SOAP API.
Below table shows the request and response of the generated REST resources
| Operation | Request | Response | |
| Create employee | POST /ws/EmployeeService/1/employee HTTP/1.1 Host: MCMRIZ01:5555 Content-Type: application/json Accept: application/json Authorization: Basic QWRtaW5pc3RyYXRvcjptYW5hZ2U= Cache-Control: no-cache Postman-Token: 0a69f487-6cac-c23e-8c48-7b60c1d6046d { "employeeName": "Yuvraj Singh", "employeeDesignation": "Cricketer", "employeeSalary": "100000", "managerId": "12345", "department": "54321" } |
{ "createEmpResponse": { "result": "Emplyee added successfully" }} |
|
| List all employees | GET /ws/EmployeeService/1/employee HTTP/1.1 Host: MCMRIZ01:5555 Accept: application/json Authorization: Basic QWRtaW5pc3RyYXRvcjptYW5hZ2U= Cache-Control: no-cache Postman-Token: 190b7a31-f3eb-e0f7-2264-7b85b29e643a |
|
|
| Read employee | GET /ws/EmployeeService/1/employee/21 HTTP/1.1 Host: MCMRIZ01:5555 Accept: application/json Authorization: Basic QWRtaW5pc3RyYXRvcjptYW5hZ2U= Cache-Control: no-cache Postman-Token: 455a9453-daa2-a809-dcdb-4157e30c9956 |
{ "getEmpResponse": { "result": { "@nil": "true" }, "employee": { "empId": 21, "empName": "Yuvraj Singh", "designation": "Cricketer", "salary": 100000, "mgrId": 12345, "department": 54321, "profilePic": "", "profileDoc": "" } }} |
|
| Update employee | PUT /ws/EmployeeService/1/employee/21 HTTP/1.1 Host: MCMRIZ01:5555 Accept: application/json Authorization: Basic QWRtaW5pc3RyYXRvcjptYW5hZ2U= Content-Type: application/json Cache-Control: no-cache Postman-Token: 0b5f008a-2247-35a6-dc04-e35552e403fa { "employeeName": "Yuvraj Singh", "employeeDesignation": "Cricketer Updated", "employeeSalary": "100000", "managerId": "12345", "department": "54321", "employeeId" : "21" } |
{ "updateEmpResponse": { "result": "Employee updated successfully" }} |
|
| Delete employee | DELETE /ws/EmployeeService/1/employee/21 HTTP/1.1 Host: MCMRIZ01:5555 Accept: application/json Authorization: Basic QWRtaW5pc3RyYXRvcjptYW5hZ2U= Cache-Control: no-cache Postman-Token: e6f5d9a6-5e8f-6aff-042f-b5125692e899 |
{ "deleteEmpResponse": { "result": "Emplyee deleted successfully" }} |
Exported into standard formats
API Gateway allows the REST definition of the SOAP API to be exported as a Swagger/RAML files for the external clients. Find the swagger file as EmployeeService.json and raml file as EmployeeService.raml in the specifications section in the API details page.
Link to the exported swagger EmployeeService.json, raml EmployeeService.raml, exported archive apiarchive.zip as a reference.
Further read:
Get to know the various ways in which you can consume and expose REST APIs in webMethods Integration Server: REST Capabilities In Integration Server