Opening a Legacy SOAP Web Service as a REST API

The request to open a legacy SOAP Web Service as a REST API often arises especially in cases where existing services are to be used by newly developed mobile applications or JavaScript-based Web applications. Options for rewriting an existing service with REST or developing a new REST API that emulates its methods are not effective solutions in terms of neither time or cost.

Apinizer enables SOAP Web services to be opened as REST and all necessary transformations can be done with configuration.

This section describes how a SOAP Web Service can be served as REST to clients.

Creating a REST API Proxy for a SOAP Web Service

1- When creating a new API Proxy, the appropriate one among the Enter URL or Upload File options can be selected for the WSDL type. In this example, the Enter URL option is used.

2- After the URL is entered and the Parse button is pressed, the REST to SOAP to REST option is selected in the Protocol Transformation section on the screen that appears. API Proxy is created by filling in the other mandatory information. 

Method Transformations

After the API Proxy is created, it is possible to customize how the methods transforms request and response messages from/to REST/SOAP message structures. For this, go to the Development Tab of API Proxy.

When All is selected in the method list on the left, icons that open the transformation settings of request messages at the top and response messages at the bottom appear in the middle section.

Clicking any of the icons opens the corresponding protocol transformation interface below. In this interface, there are Request Options and Response Options tabs. Depending on which icon the user clicks, the corresponding tab is open by default.

In this interface, configuration is made on how to convert the incoming REST request message according to the SOAP structure of the Backend API. On the left, the method to update the message structure is selected. On the right are the conversion settings for that method.

Transformation Options

When a SOAP Service is opened to clients as REST, the request and response messages need to be transformed. The JSON message from the client must be converted to an XML message before it is sent to the SOAP service, and the XML message returned by the SOAP service must be converted to a JSON message before it is sent to the client. There are several options for this operation: 

• Jackson Transformation: It is preferred in cases where the JSON message to be used in request and response messages should be plain and easy to understand. It is highly customizable compared to others and it is the most preferred method.
• JsonML Transformation: It is preferred if the JSON message to be used in request and response messages also includes XML Attribute values and XML Namespaces. Compared to others, the JSON format is more complex. Data size increases as it resembles XML representation due to Namespaces.
• Template Message: Regardless of the format of the incoming JSON message, it works on the idea of preparing the XML template to be sent to the SOAP Service. Request Data Manipulation or Response  Data Manipulation is used to populate the parameters in the XML template. It is useful in case of simple XMLs as there is no support for multiple sub-elements. It is especially preferred if it is desired to get data from the request's header or  parameters instead of the JSON message.

The available fields of each option are explained below.

Request Message Transformation Options

This section describes the details of the transformation options for request messages.

Use Jackson Transformation

Field	Description
Ignore fields with NULL	If checked, NULL values in the requested JSON message will not be added as XML Elements to the XML message to be sent to the Backend API.
Ignore EMPTY fields	If checked, empty values in the requested JSON message will not be included as XML Elements in the XML message to be sent to the Backend API.
Use xsi:nil="true" for NULL values	If checked, the xsi:nil="true" attribute is used for NULL values in the JSON message received in the request, inside the XML message to be sent to the Backend API. Otherwise, an empty element for the relevant value is inserted into the XML message. Activating the value ensures that a value sent as null in a JSON message is transmitted with the xsi:nil="true" attribute when converted to XML.
Target XPath	Specifies where the XML obtained after the incoming JSON message is converted to XML will be placed in the XML message that the SOAP service expects.
Replace Children	If the option is checked, the children of the output element of the Target XPath are deleted, replacing them with the converted part from JSON. Otherwise, the element is completely replaced.
Paths for Arrays within message	Specifies which parts of the JSON message should be interpreted as arrays. Each Path is written starting at the level of the Target XPath (the highest level if no Target XPath is given) and a # sign between the levels. Example: The expression "envelope#body#abc" indicates that the "abc" element in "envelope", inside "body" will be treated as an array. When There Is an Array Within an Array If there is an array within an array, and some objects sometimes come as arrays and sometimes as singular items, writing starts from the path of the outermost array, and the #* expression must be added after the array expressions when moving down to the lower object. For example, if the abc element is an array and the def element is an array within it, then “envelope#body#abc, envelope#body#abc#*#def” should be written in that order.
Request Data Manipulation	Any part of the original request can be transferred to a specified part of the transformed request. The Source Value/Variable specifies which part of the original request message to be transmitted, and the Target Value/Variable specifies where to put this data in the transformed message.
Show Sample Message	The Request Message created according to the settings can be displayed.

Transformed Message Example:

{
    "Add": {
        "intB": "?",
        "intA": "?"
    }
}

<soap:Envelope 
xmlns:soap="http://www.w3.org/2003/05/soap-envelope" 
xmlns:tem="http://tempuri.org/">
   <soap:Header/>
   <soap:Body>
      <tem:Add>
         <tem:intA>?</tem:intA>
         <tem:intB>?</tem:intB>
      </tem:Add>
   </soap:Body>
</soap:Envelope>

Use JsonML Transformation

Transformed Message Example:

{
    "soap:Envelope": {
        "xmlns:tem": "http://tempuri.org/",
        "soap:Header": "",
        "xmlns:soap": "http://www.w3.org/2003/05/soap-envelope",
        "soap:Body": {
            "tem:Add": {
                "tem:intA": "?",
                "tem:intB": "?"
            }
        }
    }
}

<soap:Envelope 
xmlns:soap="http://www.w3.org/2003/05/soap-envelope" 
xmlns:tem="http://tempuri.org/">
   <soap:Header/>
   <soap:Body>
      <tem:Add>
         <tem:intA>?</tem:intA>
         <tem:intB>?</tem:intB>
      </tem:Add>
   </soap:Body>
</soap:Envelope>

[
    "soap:Envelope",
    {
        "xmlns:tem": "http://tempuri.org/",
        "xmlns:soap": "http://www.w3.org/2003/05/soap-envelope"
    },
    [
        "soap:Header"
    ],
    [
        "soap:Body",
        [
            "tem:Add",
            [
                "tem:intA",
                "?"
            ],
            [
                "tem:intB",
                "?"
            ]
        ]
    ]
]

<soap:Envelope 
xmlns:soap="http://www.w3.org/2003/05/soap-envelope" 
xmlns:tem="http://tempuri.org/">
   <soap:Header/>
   <soap:Body>
      <tem:Add>
         <tem:intA>?</tem:intA>
         <tem:intB>?</tem:intB>
      </tem:Add>
   </soap:Body>
</soap:Envelope>

Use Template Message

Response Message Transformation Options

This section describes the details of the transformation options for response messages.

Use Jackson Transformation

Field	Description
Ignore fields with NULL	If selected, NULL fields in the XML message received from the Backend API are not included in the JSON message.
Ignore EMPTY fields	If selected, NULL fields in the XML message received from the Backend API are not added as empty values in the JSON message.
Write Numbers as Strings	If selected, numeric values are written as strings in the JSON message.
Use xsi:nil="true" for NULL values	If selected, it ensures that data received with the xsi:nil="true" attribute in an XML message is transmitted as null when converted to JSON.
Source XPath	Enter the XPath of the part of the response message returned as XML that will be converted to JSON.
Unwrap Element	If checked, it transforms the inside (children) of the element given with Source XPath, otherwise the element itself (with its content/children).
Paths for Arrays within message	Specifies which parts of the JSON message should be interpreted as arrays. Each Path is written starting at the level of the Target XPath (the highest level if no Target XPath is given) and a # sign between the levels. Example: The expression "envelope#body#abc" indicates that the "abc" element in "envelope", inside "body" will be treated as an array. When There Is an Array Within an Array If there is an array within an array, and some objects sometimes come as arrays and sometimes as singular items, writing starts from the path of the outermost array, and the #* expression must be added after the array expressions when moving down to the lower object. For example, if the abc element is an array and the def element is an array within it, then “envelope#body#abc, envelope#body#abc#*#def” should be written in that order.
Response Data Manipulation on Success	Any part of the original answer can be transferred to a specified part of the transformed answer. The Source Value/Variable specifies which part of the original response message to transmit, and the Target Value/Variable specifies where to put this data in the converted message. The defined operations are performed only if the Backend API/Service returns a successful response.
Show Sample Message	The Response Message created according to the settings can be displayed.

Transformed Message Example:

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope 
xmlns:soap="http://www.w3.org/2003/05/soap-envelope"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
	<soap:Body>
		<AddResponse xmlns="http://tempuri.org/">
			<AddResult>?</AddResult>
		</AddResponse>
	</soap:Body>
</soap:Envelope>

{
  "AddResponse" : {
    "AddResult" : "?"
  }
}

Use JsonML Transformation

Example:

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope 
xmlns:soap="http://www.w3.org/2003/05/soap-envelope" 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
	<soap:Body>
		<AddResponse xmlns="http://tempuri.org/">
			<AddResult>?</AddResult>
		</AddResponse>
	</soap:Body>
</soap:Envelope>

{
  "soap:Envelope" : {
    "xmlns:xsd" : "http://www.w3.org/2001/XMLSchema",
    "xmlns:soap" : "http://www.w3.org/2003/05/soap-envelope",
    "xmlns:xsi" : "http://www.w3.org/2001/XMLSchema-instance",
    "soap:Body" : {
      "AddResponse" : {
        "xmlns" : "http://tempuri.org/",
        "AddResult" : "?"
      }
    }
  }
}

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope 
xmlns:soap="http://www.w3.org/2003/05/soap-envelope" 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
	<soap:Body>
		<AddResponse xmlns="http://tempuri.org/">
			<AddResult>?</AddResult>
		</AddResponse>
	</soap:Body>
</soap:Envelope>

[
	"soap:Envelope",
	{
		"xmlns:xsd": "http://www.w3.org/2001/XMLSchema",
		"xmlns:soap": "http://www.w3.org/2003/05/soap-envelope",
		"xmlns:xsi": "http://www.w3.org/2001/XMLSchema-instance"
	},
	[
		"soap:Body",
		[
			"AddResponse",
			{
				"xmlns": "http://tempuri.org/"
			},
			[
				"AddResult",
				"3"
			]
		]
	]
]

Use Template Message