SOAP and WSDL Legacy Integration

with an Open Source API Gateway

The Membrane API Gateway provides comprehensive support for legacy protocols and formats such as SOAP-based Web Services and WSDL descriptions. It enables modern API management for existing SOAP services and helps integrate legacy systems without changing backend implementations. Because Membrane is a Java based API Gateway, it can leverage the platform’s mature XML technologies for routing, validation, and transformation. Existing integration solutions can also be migrated from obsolete Enterprise Service Bus infrastructures to a lightweight API Gateway.

The open source API Gateway supports legacy integration scenarios including:

SOAP message routing based on body elements, SOAPAction, or WS-Addressing
WSDL deployment, validation, configuration, and rewriting
SOAP to REST and REST to SOAP conversion
XML transformations using XSLT, XPath, and namespace-aware processing

This article provides an overview of how Membrane API Gateway can be used for SOAP and WSDL based legacy integration.

1 SOAP Message Routing

SOAP Web Service traffic is typically transported over HTTP and can therefore be routed through an API Gateway together with modern REST APIs and JSON messages. This allows you to manage SOAP services and REST APIs in one place. The Membrane API Gateway provides a dedicated soapProxy for routing SOAP messages, acting as a specialized API endpoint for Web Services.

SOAP message routing with an API Gateway using soapProxy

SOAP services can be routed in different ways depending on the client and framework. Some SOAP stacks route messages using the XML wrapper element in the SOAP body, others rely on the SOAPAction HTTP header, and some use WS-Addressing headers. The API Gateway supports all of these routing strategies.

The direct child element of the SOAP body typically corresponds to the SOAP operation or backend function. This element can be used to route requests.

<s11:Envelope xmlns:s11="http://schemas.xmlsoap.org/soap/envelope/">
    <s11:Body>
        <c:getCity xmlns:c="https://predic8.de/cities">
            <name>Delhi</name>
        </c:getCity>
    </s11:Body>
</s11:Envelope>

While REST APIs are usually selected by matching the request path, SOAP routing can use XML-aware matching. Membrane supports XPath-based routing with namespace handling. The following configuration routes requests based on the SOAP body element shown above.

soapProxy:
  port: 2000
  test: //c:getCity
  language: xpath
  xmlConfig:
    namespaces:
      - prefix: c
        uri: https://predic8.de/cities

Older SOAP services often rely on the SOAPAction HTTP header for routing.

POST /city-service HTTP/1.1
SOAPAction: https://predic8.de/city-service/get

The routing expression can also match HTTP headers. The following example routes requests using the SOAPAction header.

api:
  port: 2000
  test: header.SOAPAction == 'https://predic8.de/city-service/get'

WS-Addressing headers can also be used for SOAP routing. These values can be matched using XPath expressions in the same way as SOAP body elements.

2 WSDL Support in the API Gateway

The Web Services Description Language (WSDL) defines SOAP-based Web Services including operations, message structures, data types, and endpoints. An API Gateway can use a WSDL document to deploy services, route requests, and validate SOAP messages. This makes WSDL a powerful foundation for managing legacy Web Services.

2.1 WSDL Deployment

A WSDL document contains everything needed to deploy a SOAP Web Service. The API Gateway can load the WSDL and automatically configure routing and message handling. In Membrane, a minimal configuration with the listen port and WSDL location is sufficient to deploy the service.

soapProxy:
  port: 2000
  wsdl: https://www.predic8.de/city-service?wsdl

soapProxy:
  port: 2000
  wsdl: https://www.predic8.de/city-service?wsdl

2.2 WSDL Rewriting

When an API Gateway exposes a SOAP Web Service, it should also provide the corresponding WSDL to clients. Before returning the WSDL, the document must be rewritten so that service endpoints point to the API Gateway instead of the backend service. Without rewriting the service location and referenced XSD include and import elements, clients would bypass the gateway and connect directly to the backend.

WSDL rewriting in an API Gateway replacing backend service endpoints

The Membrane soapProxy automatically rewrites endpoint addresses in WSDL documents and updates all referenced XML Schema includes and imports recursively. This ensures that clients access services through the API Gateway while avoiding duplication of WSDL and schema files.

2.3 WSDL Validation

A WSDL document defines message structures, XML schemas, data types, and constraints such as string lengths or allowed value ranges. An API Gateway can use this information to validate incoming and outgoing SOAP messages. WSDL-based validation is an important security layer that helps prevent entire classes of API attacks, including injection, malformed XML payloads, information disclosure, and broken object-level authorization.

WSDL validation of SOAP messages in an API Gateway

WSDL validation can be enabled directly on Membrane’s soapProxy, allowing the gateway to enforce schema constraints and reject invalid SOAP requests before they reach backend services.

3 REST to SOAP and SOAP to Rest Conversion

API Gateways can bridge the gap between legacy services and modern REST APIs. This makes it possible to modernize interfaces step by step instead of replacing entire systems at once. Depending on the direction of the migration, the gateway can expose a REST API in front of a SOAP backend or provide a SOAP facade for a modern REST service.

3.1 REST API Fassade for SOAP Services

Many legacy systems expose functionality through SOAP Web Services, while modern clients expect REST APIs with JSON payloads. An API Gateway can bridge this gap by exposing a REST API facade in front of a SOAP service. The gateway converts incoming REST requests into SOAP messages and transforms SOAP XML responses into JSON.

SOAP to REST API Conversion at the API Gateway

A REST API facade can be secured using modern authentication and authorization mechanisms such as OAuth2, OpenID Connect (OIDC), or API keys.

3.2 SOAP Fassade for REST APIs

In many legacy integration scenarios, old SOAP clients cannot be replaced immediately. They may still be the only supported interface for existing business applications, or there may be neither the time nor the budget to migrate all clients to modern REST APIs at once. A common situation is that an existing backend service is modernized and exposed as a REST API, while older client applications still expect a SOAP Web Service.

In this case, the API Gateway can provide a SOAP facade in front of the REST API. It accepts SOAP requests from legacy clients, maps them to REST calls, and transforms the API response back into a SOAP message. This allows backend systems to evolve without breaking compatibility with existing SOAP-based integrations.

With this approach, you can gradually replace an obsolete Enterprise Service Bus with a lightweight open source API Gateway and continue integrating legacy systems while modernizing your architecture. Detailed examples and tutorials show how to implement SOAP-to-REST and REST-to-SOAP integration patterns with Membrane.