Learn the no-code process for onboarding services, creating REST facades for SOAP backends (Publish) or SOAP facades for REST backends (Consume).
Applies to1.7.1
Overview of Service Onboarding
Onboarding is the no-code process for converting a SOAP or REST service contract into a live, managed API endpoint. This process automatically generates a machine-readable contract, creates a deterministic full-field mapping between the source and target formats, and enables observability from the first call, all without requiring custom mediation scripts.
The platform supports two directions for service onboarding:
Publish (REST-over-SOAP): This flow creates a REST/JSON facade for an existing SOAP backend. API consumers interact with a generated OpenAPI v3 contract, while the platform handles the conversion to and from the backend SOAP service.
Consume (SOAP-over-REST): This flow creates a SOAP facade for a modern REST backend, allowing legacy SOAP clients to continue operating without modification. The platform ingests SOAP requests, converts them to REST, calls the new backend, and wraps the response in a SOAP envelope. The consumer-facing contract is a WSDL generated and served by the platform.
How it Works
The onboarding process follows a structured, multi-step flow that varies depending on whether you are publishing a REST facade or consuming a REST service with a SOAP facade.
Publish Flow: Creating a REST Facade for a SOAP Backend
The Publish flow takes a WSDL contract and exposes it as a modern REST/JSON API.
flowchart TD
A[Discover] --> B(Import WSDL);
B --> C(Configure Backend);
C --> D(Review OpenAPI);
D --> E(Publish & Version);
The process consists of the following steps:
Discover (Optional): If your gateway forwards traffic to the platform, services can be discovered automatically from live traffic. You can then select a discovered service to begin onboarding. Alternatively, you can skip this and start directly by importing a WSDL.
Import WSDL: Provide the SOAP contract by uploading a WSDL file, pasting a URL, or pasting the raw XML. The platform parses the contract to materialize a per-operation request/response schema and infers a draft configuration for the service, backend endpoint, SOAP version, and authentication.
Configure Backend: Define the connection details for the backend SOAP service. This includes the endpoint URL, SOAP version, authentication method, and resiliency settings like timeouts, retries, and multi-backend routing with failover and health checks.
Review OpenAPI: The platform generates an OpenAPI v3 specification based on the WSDL and your configuration. This specification includes the converted schemas and per-operation fault schemas. You should review this contract before activating the service.
Publish & Version: Before going live, a publish-readiness gate runs diagnostics to check mappings, backend configuration, WSDL drift, and the success of a test SOAP call. A successful publish activates an immutable snapshot of the mapping. You can activate new versions or roll back to a previous version at any time.
NOTE
Zero-Touch Shortcut: The "zero-touch autopilot" feature can collapse the Discover, Import, and Generate steps into a single action. The platform automatically imports the WSDL, generates the service and operations, and provides a readiness score for each operation, leaving only the final review and publish steps.
Consume Flow: Creating a SOAP Facade for a REST Backend
The Consume flow is used to modernize a backend to REST while maintaining compatibility for existing SOAP clients. It creates a SOAP facade that proxies requests to the new REST service.
flowchart TD
subgraph Inputs
A[Service Identity]
B[Old WSDL]
C[REST OpenAPI]
D[REST Backend Config]
E[Example Payloads]
end
Inputs --> F(Mapping Review);
F --> G(Publish);
G -- Serves --> H(Generated WSDL);
This flow requires several inputs to ground the conversion:
Service identity information.
The original WSDL contract that legacy clients use.
The OpenAPI contract for the new REST backend.
The REST backend configuration, including its URL and authentication details.
Example payloads to aid in mapping.
The runtime accepts inbound SOAP 1.1 or 1.2 requests, converts them into REST calls (including handling outbound REST authentication), and wraps the resulting REST response in a SOAP envelope to send back to the client. The contract for this new endpoint is the WSDL that the platform serves back to consumers.
Runtime URL Structure
All runtime API calls, for both Publish and Consume flows, use a standardized URL path structure.
The direction segment (publish or consume) is mandatory and determines which conversion engine handles the request. The published OpenAPI servers[].url (for Publish) and the WSDL <soap:address> (for Consume) both include this segment to ensure generated clients use the correct path.
Path Parameters
Name
Description
`publish
consume`
environment
The deployment environment for the service.
serviceKey
The unique identifier for the onboarded service.
operationPath...
The path representing the specific operation being invoked.
Features of an Onboarded Service
Every service successfully onboarded to the platform gains the following capabilities:
Deterministic Mapping: A full-field mapping is automatically generated from the source contract.
Hierarchical Conversion Options: Control conversion behavior at the system, service, operation, or field level.
Field-Level Overrides: Manually adjust mappings for specific fields in the UI to handle exceptions.
Validation Modes: Configure request and response validation to be off, shadow|monitor (validate and log but do not block), or enforce (block invalid messages).
Immutable Versioning: Mappings are versioned and immutable, with simple activation and rollback capabilities.
Observability: Gain immediate access to dashboards, logs, and audit trails for all traffic through the service.
Troubleshooting
HTTP 400 Bad Request
Condition: A request is made to a runtime URL without the leading /publish or /consume path segment.
Cause: The platform requires the direction segment to route the request to the correct processing engine.
Resolution: Ensure all client requests are sent to the full, canonical path, including the direction segment.
Publish Readiness Gate Failures
During the "Publish & version" step, the readiness gate may prevent activation if it detects issues. Common failure sources include:
Mapping diagnostics reporting errors.
Invalid or unreachable backend configuration.
A failure during the test SOAP call to the backend.
Significant drift detected between the imported WSDL and the live backend's contract.
