Learn the no-code process for onboarding SOAP and REST services. Covers Publish (REST facade), Consume (SOAP facade), and SOAP Broker directions.
Overview
Service onboarding is the no-code process for converting a SOAP or REST service contract into a live, managed endpoint. This process automatically generates a machine-readable contract, creates a deterministic full-field mapping between the original and new formats, and enables observability features without requiring a custom mediation script.
Since version 1.0, the platform supports three onboarding directions:
Publish (SOAP-to-REST): Creates a REST/JSON facade over an existing SOAP backend. API consumers call a generated REST API, and the runtime translates these calls into SOAP requests for the backend. The published contract is an OpenAPI v3 document.
Consume (REST-to-SOAP): Creates a SOAP facade over a modern REST backend. This allows legacy SOAP clients to continue operating while the backend is migrated to REST. The runtime accepts SOAP requests, translates them to REST, and wraps the REST response in a SOAP envelope. The published contract is a WSDL document served from the endpoint.
SOAP Broker (SOAP-to-SOAP): Places the platform in the path of an existing SOAP service to provide traffic logging, metrics, and access control without altering the message format. The message is passed through unchanged, and the service's contract remains its own original WSDL.
The Publish Flow
The Publish direction transforms a WSDL into a live REST API. The process follows a sequence of steps from initial contract import to a versioned, live endpoint.
flowchart TD
subgraph "Optional"
A[Traffic Discovery]
end
B[Import WSDL]
C[Configure Backend]
D[Review Generated OpenAPI]
E[Publish & Version]
A --> B
B --> C
C --> D
D --> E
Discover (Optional): If the gateway is configured to forward traffic to the platform, services can be discovered automatically from live traffic. You can onboard a service directly from the list of discovered services. Alternatively, you can start by providing a WSDL file. See the documentation on traffic-driven discovery.
Import WSDL: Provide the SOAP contract by uploading a WSDL file, pasting a URL, or pasting the raw XML content. The parser analyzes the contract to define operations, infer a draft service configuration, and suggest the SOAP version and backend endpoint. See Import a WSDL.
Configure Backend: Define the backend service details, including its endpoint URL, SOAP version, and authentication method. You can also configure advanced settings like timeouts, retries, and multi-backend routing with failover and health checks. See Configure the backend.
Review OpenAPI: The platform generates an OpenAPI v3 contract based on the WSDL and your selected conversion options. This includes schemas for each operation and potential faults. Review this generated contract before activating the service. See Generate & review the OpenAPI.
Publish & Version: Before publishing, a readiness gate runs diagnostics on the mapping, backend configuration, and WSDL drift, and performs a test SOAP call. Activating a service creates an immutable, versioned snapshot of the mapping. You can roll back to any previous version at any time. See Publish & version a service.
Zero-Touch Autopilot
The zero-touch autopilot feature can collapse the discovery, import, and generation steps into a single action. The platform automatically imports the WSDL, generates the service and its operations, creates the mappings, and provides a readiness score for each operation, leaving only the final review and publishing steps for you to complete.
The Consume Flow
The Consume direction is used to modernize a backend to REST while maintaining compatibility with existing SOAP clients. This flow requires four inputs to create the SOAP facade:
Service identity
The original WSDL contract for the legacy service
The OpenAPI contract for the new REST backend
The REST backend configuration, including authentication details
The runtime accepts inbound SOAP 1.1 or 1.2 requests, converts them into REST calls against the new backend, and wraps the REST response in a SOAP envelope to send back to the client. The consumer-facing contract is the WSDL that is served back from the consume endpoint.
The SOAP Broker flow allows you to gain observability and control over an existing SOAP service without any contract conversion. To broker a service, you register it, provide its backend endpoint URL, and configure access control policies.
The message is forwarded to the backend byte-for-byte. Because there is no conversion, there is no mapping step and no generated contract to review.
Every service onboarded to the platform gains a standard set of capabilities:
Deterministic Mapping: A full-field mapping is automatically generated from the service contract. See How mapping works.
Conversion Options: A hierarchy of options at the system, service, operation, and field levels allows for fine-grained control over type conversion. See the Conversion options reference.
Field-Level Overrides: A UI is available to manually override mappings for exceptional cases. See Field-level overrides.
Validation Modes: Inbound requests and outbound responses can be validated against the contract with modes for off, shadow (monitor), or enforce. See Validation modes.
Immutable Versioning: Mappings are versioned and immutable, allowing for safe activation and rollback.
Observability: All calls generate data for dashboards, logs, and audit trails from the first invocation. See Observability.
Runtime URL Structure
All runtime invocations, regardless of direction, use a standardized, prefixed URL path.
The initial path segment (publish or consume) is required. A request to a path without this direction segment will be rejected.
The published OpenAPI servers[].url (for Publish) and the emitted WSDL <soap:address> (for Consume) both include the full, canonical path with the direction segment, ensuring that generated clients target the correct endpoint.
Path Parameters
Parameter
Description
{publish|consume}
Required. The service direction. Use publish for REST facades over SOAP backends or consume for SOAP facades over REST backends.
{environment}
The target environment for the service invocation.
{serviceKey}
The unique identifier for the onboarded service.
{operationPath...}
The path identifying the specific operation to be invoked.
Troubleshooting
HTTP 400 Bad Request
Cause: An incoming request was sent to a runtime URL that is missing the required {publish|consume} direction segment in its path.
Meaning: The platform could not determine which processing flow (Publish or Consume) to apply to the request.
Resolution: Ensure the client is configured to use the full, canonical URL path, including either /publish/ or /consume/ after the base URL.
