[Discussion]SOAP API passthrough support for API Platform gateway

[SavinduDimal]

Problem

The current WSO2 API Platform Gateway supports REST, WebSub, WebBroker, MCP, and LLM APIs, but it does not support SOAP services. This creates a feature gap between WSO2 API Manager and WSO2 API Platform. In addition, enterprises with existing SOAP-based services cannot expose or manage those services through WSO2 API Platform and are unable to leverage the platform's gateway capabilities such as authentication, authorization, throttling, policy enforcement, and analytics for SOAP traffic.

SOAP APIs cannot be treated as normal REST APIs because:

• SOAP services usually expose a single HTTP endpoint.
• SOAP operations are not identified by URL path and HTTP method.
• Gateway-generated errors must be returned as SOAP Faults instead of JSON error responses.
• SOAP operations are commonly identified using SOAPAction, SOAP 1.2 action, or the SOAP body element.

Proposed Solution

A new SoapApi resource should be introduced alongside existing API kinds. This proposes a simpler model similar to the current WSO2 API-M passthrough model: one wildcard route per SOAP API without defining operations.

apiVersion: gateway.api-platform.wso2.com/v1alpha1
kind: SoapApi
metadata:
  name: calculator-v1
spec:
  displayName: Calculator SOAP API
  version: v1.0
  context: /calculator/$version
  upstream:
    main:
      url: http://backend:3002/calculator/v1/soap11
  policies:
    - name: api-key-auth
      version: v1
      params:
        key: X-API-Key
        in: header

• A generic POST route is created for a SOAP API to handle all the requests.
• A GET route is created to support WSDL retrieval.
• With this approach analytics will not be aware of the SOAP Action.
• The design reuses existing policies wherever possible.

SOAP Fault Formatter

Gateway-generated errors (401 unauthorized, 429 throttled, 500 Internal server errors) must be returned as SOAP Faults.

The fault formatter will:

• Handle the gateway generated errors.
• Apply only to APIs with SoapApi kind traffic.
• Preserve the original HTTP status code.
• Preserve important transport headers.
• Infer SOAP 1.1 or SOAP 1.2 fault format from the request Content-Type.
• Escape the original error body inside the SOAP element.

[SavinduDimal]

Meeting Notes (15th June 2026)

• Omit operation level (SOAP action based) handling.
• Omit WSDL import in the first phase.
• Introduce an agent skill to convert WSDL to SoapApi definition.
• SOAP envelope validation will not be implemented in the first phase.
• WS-Security, SOAP to REST transformation will not be handled in the phase 1.
• WSDL response rewriting is designated to be handled by introducing a specific WSDL rewrite policy.

Fault handling strategy

• The current fault flow is too rigid and does not allow users to easily customize error messages or override status codes at the API or global level.
• Current SOAP API, gateway generated fault formatter might help with the global/API level fault handler
• Check the feasibility of implementing this