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.
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. In case there is an array element in array element, longest path must be written first. For example assuming "abc" array element has an "def" array element, there must be two paths in order like this: "envelope#body#abc#def, envelope#body#abc"
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:

JSON Request Message Expected by API Proxy from Client

XML Request Message that Backend API/Service expects

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

YML

<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>

XML

Use JsonML Transformation

Field	Description
Use JSON Object	Converts XML Elements to JSON Objects.
Use JSON Array	Converts XML Elements to JSON Arrays.
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:

Transformation Type

JSON Request Message Expected by API Proxy from Client

XML Request Message that Backend API/Service expects

JSON Object

{
    "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": "?"
            }
        }
    }
}

YML

<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>

XML

JSON Array

[
    "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",
                "?"
            ]
        ]
    ]
]

YML

<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>

XML

Use Template Message

Field	Description
Template Message	XML request message template that the Backend API/Service expects
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.

Response Message Transformation Options

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

Use Jackson Transformation

	Açıklama
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 an Array. Each Path is written starting at the level of the Source XPath (the highest level if no Source XPath is given), with a # sign between the levels. Example: envelope#body#abc specifies that the abc element in the envelope, inside the body, will be treated as an array. In case there is an array element in array element, longest path must be written first. For example assuming "abc" array element has an "def" array element, there must be two paths in order like this: "envelope#body#abc#def, envelope#body#abc"
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 Response Message returned by Backend API/Service

JSON Response Message Returned by API Proxy to Client

<?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>

XML

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

YML

Use JsonML Transformation

Field	Description
Use JSON Object	Converts XML Elements to JSON Objects.
Use JSON Array	Converts XML Elements to JSON Arrays.
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.

Example:

Transformation Type

XML Response Message returned by Backend API/Service

JSON Response Message Returned by API Proxy to Client

JSON Object

<?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>

XML

{
  "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" : "?"
      }
    }
  }
}

YML

JSON Array

<?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>

XML

[
	"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"
			]
		]
	]
]

YML

Use Template Message

Field	Description
Template Message	JSON response message to be returned to the client
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.