Consume Direction (SOAP Facade)

Overview

The Consume direction provides a SOAP facade that allows API publishers to modernize a backend service to REST while maintaining compatibility with legacy SOAP clients. When a service is configured in the Consume direction, the platform ingests inbound SOAP envelopes from API consumers, transforms each call into a REST request, and sends it to the migrated REST backend. It then wraps the REST response from the backend into a SOAP envelope and returns it to the original consumer.

This mechanism enables a backend migration to REST without requiring a coordinated, simultaneous cutover of all its clients. The API consumer continues to interact with a SOAP endpoint, unaware of the backend modernization.

The Consume direction is the inverse of the Publish direction, which exposes a REST facade for a SOAP backend. The direction is configured per service and is fixed once set.

When to Use Consume Direction

Use the Consume direction when you have migrated a backend service from SOAP to REST but cannot immediately update the clients that depend on it. This is common in scenarios involving:

• Legacy partner integrations that are difficult or slow to change.
• Internal applications that are outside of your team's control.
• A phased migration where clients will be updated over time, but the backend must be modernized first.

The SOAP facade allows the backend to be migrated independently, decoupling its evolution from the client's lifecycle.

How it Works

The platform acts as a stateful intermediary, performing a bidirectional transformation between the SOAP and REST protocols. This process is guided by a mapping synthesized from multiple sources to ensure accuracy.

flowchart TD
    subgraph Legacy Consumer
        A[SOAP Client]
    end
    subgraph API Platform
        B(SOAP Facade)
    end
    subgraph Migrated Backend
        C[REST Service]
    end

    A -- 1. SOAP Request --> B
    B -- 2. Converts to REST Request --> C
    C -- 3. REST Response --> B
    B -- 4. Converts to SOAP Response/Fault --> A

A reliable SOAP-to-REST mapping requires more than just the two API contracts (WSDL and OpenAPI), as field names, data structures, and semantics may have changed during the migration to REST. A mapping based solely on the contracts could silently produce incorrect data.

To prevent this, the platform's mapping engine requires four distinct inputs to create a safe, production-ready service.

Four Grounding Inputs

The onboarding wizard guides the API publisher through providing these four inputs in order:

1. Old WSDL: The SOAP contract that existing clients are built against. The platform uses this to validate inbound requests and to serve a derived WSDL back to consumers.
2. REST OpenAPI 3 Spec: The contract for the new, migrated REST backend. This defines the target for the outbound REST calls.
3. REST Backend Configuration: The base URL of the REST backend and the authentication credentials required to access it.
4. Payload Examples: A set of real SOAP request/response pairs and their corresponding REST request/response pairs. These examples serve as "mapping evidence," resolving ambiguities that the WSDL and OpenAPI specs alone cannot, such as renamed fields, reshaped wrapper elements, or changed enum values.

A service cannot be published until at least one example payload is provided for each operation. These examples can be uploaded manually or ingested automatically from gateway traffic logs.

Onboarding Process

The onboarding wizard enforces the collection of these inputs before a service can be published. The high-level flow is as follows:

Service identity → Old WSDL → REST OpenAPI → REST backend config (incl. auth) → Example payloads → Mapping review → Publish

Runtime Behavior

WSDL Serve-back

Because the consumer-facing contract is SOAP, the platform serves a WSDL document at the service's runtime endpoint. This WSDL is derived from the original WSDL provided during setup, but the platform modifies the <soap:address location="..."> attribute to point to the correct runtime URL for the service.

The derived WSDL is available for download at both the draft and published stages of the service's lifecycle.

Inbound SOAP Support

The inbound SOAP listener accepts both SOAP 1.1 and SOAP 1.2 requests. The runtime automatically detects the version from the request's Content-Type header and body.

The platform resolves the target operation using the message's qualified name (QName) and SOAPAction header, cross-referencing them with the service's configuration. Any faults generated by the platform (e.g., due to a malformed request) will match the fault structure of the inbound SOAP version.

Runtime URL Shape

All invocations of a Consume service use a direction-prefixed runtime URL. The path structure is:

/consume/{environment}/{serviceKey}/{operationPath...}

A request to a path that does not include the /consume prefix will be rejected with an HTTP 400 error.

Configuration

Outbound REST Authentication

The platform supports several authentication methods for the outbound REST call to your migrated backend. These are the same types available for a Publish direction service.

All credentials are encrypted at rest and are never exposed in logs or API responses.

Troubleshooting

See Also

• Onboarding overview
• Configure the backend
• How mapping works
• SOAP & XSD support

All SOAP-to-REST docs