Consuming  legacy SOAP Web Services normally requires a middleware integration tool or custom code to develop a modern JSON-based REST Web Service—essentially a wrapper around the legacy SOAP Web Service to improve usability. But acquiring, developing and maintaining an integration tool or custom code for this purpose is a huge overhead. In addition, there is an investment in learning to use the integration tool. I speak from experience, working both as an integration developer and in engineering roles, building products that expose and consume SOAP Web Services.

To help smooth this integration headache, the Kong customer experience team developed a SOAP Transformation plugin that removes the need for an integration layer or custom code. 

The plugin can convert JSON to XML SOAP and vice versa, all via configuration. And because the plugin deploys to Kong Gateway using the Kong Lua PDK, it’s fast!

What is SOAP (Simple Object Access Protocol)?

SOAP, Simple Object Access Protocol, Web Services have been around for a long time, and not too long ago was the default when it came to exposing functionality using a common format. SOAP is a standards-based web services access protocol that relies on XML to describe the web service and for all request and response messages. (Learn more about all the different type of APIs.)

While SOAP includes many benefits, the heavy nature of XML and the marshaling and unmarshaling of XML to programmatic entities such as Java objects, impacts performance and scalability. Add to that the learning curve to understand SOAP, and it’s clear why there was a need for an alternative. 

REST Web Services are now the de-facto standard. But SOAP Web Services still exist and will be around for a long while yet. 

SOAP XML Overview

SOAP XML consists of a few main components that we need to consider when utilizing the SOAP Transformation plugin. These elements are:

• Envelope – identifies the XML document as a SOAP message
• Header – contains header information
• Body – contains request and response information
• Fault – contains errors and status information

XML namespaces are another key component of XML SOAP. A namespace is a collection of names that one could use as element or attribute names, and the namespace uniquely describes these elements or attributes to avoid conflicts.

Using an online SOAP Web Service as described here, it sums two numbers and returns the result. Let’s look at the simple XML SOAP request message required to call this Web Service:

<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://www.w3.org/2003/05/soap-envelope"
xmlns:demo="http://tempuri.org">
  <soap:Body>
    <demo:Add>
      <intA>5</intA>
      <intB>1</intB>
    </demo:Add>
  </soap12:Body>
</soap:Envelope>

And the corresponding XML SOAP response from the Web Service:

​​<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/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>6</AddResult>
      </AddResponse>
   </soap:Body>
</soap:Envelope>

As you can see, even though the functionality exposed by the Web Service is simple, the XML SOAP is complicated. And obviously, as the functionality and requirements grow, so does the XML, becoming even more complicated.

Now, let’s look at a JSON over REST equivalent request message:

{
    "body":{
       "Add":{
          "intA":5,
          "intB":1
       }
    }
 }

And equivalent response message:

{
    "body":{
       "addResponse":{
          "addResult":6
       }
    }
 }

As you can see, the messages are easier to read and easier to consume. Therefore, marshaling and unmarshaling to programmatic entities will be simpler and quicker, resulting in better performance and scalability.

SOAP Converter – Transformer Plugin Overview

This plugin transforms a JSON request into a XML SOAP request and then transforms the corresponding XML SOAP response into a JSON response.

Here’s how the transformation of element names from SOAP to JSON and vice versa works:

Convert JSON to SOAP 

• Capitalizes all element names.
• Defines XML sequences that specify the order of XML elements in the plugin configuration. This is required since JSON does not enforce ordering.
• Adds the namespace and namespace prefix to each element as specified in the plugin configuration.

Convert SOAP to JSON

• Changes all element names to camelcase.
• Strips the namespace and namespace prefixes.
• Converts SOAP repeating elements to JSON arrays and specifies any single element array names in the plugin configuration.
• Converts SOAP Faults to equivalent REST 40* status codes.

Using the SOAP Web Service described earlier, the following plugin configuration will perform the JSON to SOAP and SOAP to JSON conversion.

curl --request POST \
  --url http://localhost:8001/<My-Service>/plugins \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "soap-request-transformer",
    "config": {
        "soap_request_body_elements_and_namespaces": [],
        "property_ordering": [
            "intA",
            "intB"
        ],
        "json_request_header_object_names": null,
        "soap_response_operation": "AddResponse",
        "soap_response_array_elements": [
            "AddResult"
        ],
        "mismatched_response_properties": null,
        "json_request_body_object_names": [],
        "soap_action": "\"http://tempuri.org/Add\"",
        "soap_request_body_namespace": "http://tempuri.org",
        "soap_request_operation": "Add",
        "mismatched_request_properties": null,
        "soap_version": "1.2",
        "soap_request_body_namespace_prefix": "tem",
        "soap_request_header_namespace": null,
        "response_payload": null,
        "soap_response_numeric_object_names": null,
        "remove_attr_tags": true,
        "error_code_to_http_status_code": null,
        "soap_prefix_request": "soap",
        "soap_header_tag": null
    }
}'

To demonstrate the SOAP Transformation plugin in action, I will use Insomnia, an open source REST Client developed by Kong. The plugin has been applied to a service object in Kong Gateway Enterprise via the Kong Admin API using the plugin configuration described above.

I mentioned the plugin execution time was fast! Looking at the response HTTP headers as displayed in the image below, we can see that:

• X-Kong-Proxy-Latency  is 2 milliseconds, and
• X-Kong-Upstream-Latency is 166 milliseconds (the time waiting for the SOAP Web Service to respond).

X-Kong-Proxy-Latency is the request and response processing time within Kong Gateway Enterprise and the SOAP Transformation plugin. Below is an extract from Kong documentation on the Response behavior:

• X-Kong-Proxy-Latency: <latency>, where latency is the time in milliseconds between Kong receiving the request from the client and sending the request to your upstream service.
• X-Kong-Upstream-Latency: <latency>  where latency is the time in milliseconds that Kong was waiting for the first byte of the upstream service response.

Conclusion

Consuming SOAP Web Services is not straightforward, requiring specialist integration tools and knowledge or coding expertise in languages such as Java. Both are heavy investments. For those API Proxy use cases where legacy SOAP Web Services coexist with REST Web Services, the SOAP Transformation plugin can avoid needing an integration layer.

If you are an existing customer and want more information on the SOAP Transformer plugin, contact your Kong Customer Experience Manager. 

If you’re not yet a customer, then reach out to your local Kong Sales Team.

Want more tutorials?

• What is CI/CD?
• Kong API Gateway on Kubernetes with Pulumi
• JWT Authentication for Microservices: API Gateway Tutorial
• Using Kong Kubernetes Ingress Controller as an API Gateway
• APM With Prometheus and Grafana on Kubernetes Ingress
• Kubernetes Ingress gRPC Example With a Dune Quote Service