Loading…
Loading…
Understand the core concepts of the SOAP-to-REST platform, including services, operations, mappings, and the publish/consume model for API transformation.
This document defines the core concepts and vocabulary for the SOAP-to-REST platform. These terms map directly to resources in the API, labels in the user interface, and s2r_-prefixed tables in the database. A clear understanding of these concepts is essential for operating and integrating with the platform.
The platform's primary function is to create and manage integrations that translate between SOAP and REST protocols. It does this by defining a set of related resources—Services, Operations, Mappings, and Environments—that together form a complete, versioned, and observable integration unit. The concepts described here have been part of the General Availability product since version 1.0.
The following terms represent the fundamental building blocks of the platform.
A Service is the primary unit of integration, representing a single onboarded SOAP or REST backend. It is the resource that is published, versioned, and monitored. Each service is defined by:
serviceKey.PUBLISH or CONSUME).An Operation represents a single callable action within a Service. It corresponds to a operation in a WSDL contract. For example, a SOAP GetCustomer operation might be exposed as a GET /customers/{id} REST endpoint in the PUBLISH direction.
Each operation has its own distinct request mapping, response mapping, and fault handling rules. Most detailed configuration, such as validation settings and Conversion Option overrides, is applied at the operation level.
A Mapping is the set of deterministic, rule-based translations between a SOAP message's XML tree and an operation's REST/JSON structure. The platform generates mappings from a source contract (WSDL/XSD for PUBLISH or OpenAPI for CONSUME).
This "full-field mapping" covers the entire request and response data structure, including all elements, attributes, optional fields, and declared faults. The generation is deterministic, meaning the same contract always produces the same mapping. The platform does not use a transformation language or require manual mediation logic. You can apply field-level overrides to adjust the default behavior for specific business requirements.
Mappings are captured as immutable, versioned snapshots (e.g., v1, v2). Once created, a mapping version can never be changed. To deploy a mapping, you activate a specific version to handle live traffic. You can also roll back to any previous version instantly.
When an updated contract is imported, the platform creates a new mapping version instead of modifying the active one. It also generates a change report detailing differences from the previous version, such as added or removed operations, breaking changes, and per-operation deltas. This ensures that service evolution is safe and predictable.
A Service operates in one of two directions:
PUBLISH: Exposes a REST API to consumers that proxies a SOAP backend. The platform receives REST/JSON requests, converts them to SOAP, calls the backend SOAP service, and converts the SOAP response back to REST/JSON. The published contract is an OpenAPI v3 document.
CONSUME: Exposes a SOAP endpoint to legacy clients that proxies a REST backend. The platform receives SOAP requests, converts them to REST/JSON, calls the backend REST service, and wraps the REST response in a SOAP envelope. The published contract is a WSDL document. Outbound REST calls support several authentication methods: none, basic, bearer token, OAuth2 client-credentials, API key in a header, and mutual TLS.
Discovery is the process by which the platform automatically identifies SOAP services by observing live traffic at the network edge, eliminating the need for manual WSDL uploads. Discovered services are listed in a central view with request counts over 24-hour, 7-day, and 1-month periods.
To ensure fast query performance, these counts are derived from pre-computed aggregation tables, not by querying raw logs. Consumer attribution is determined using forwarded headers such as X-Client-IP, X-Forwarded-For, or Forwarded.
A Connector is an integration component that enables the platform to discover services and ingest traffic from a specific edge product, such as a load balancer or an API gateway. Each connector is designed to work with a vendor's specific management APIs or traffic log feeds.
As of v1.0, built-in connectors are available for:
A generic-HTTP receiver is also provided for integrating with any edge device that can export HTTP traffic logs. This receiver includes per-vendor parsers and a dead-letter queue.
A Learned Example is a real request/response payload, including headers, captured from production traffic and associated with a specific service operation. These examples provide API consumers with a realistic view of the data flowing through an operation and serve as evidence during mapping reviews. Learned examples are processed from the raw traffic ingest feed.
A Conversion Option is a tunable parameter that controls the behavior of the SOAP-to-REST transformation. Options can be set at a global platform level and overridden at the service, operation, or individual field level. The most specific setting takes precedence (field > operation > service > platform).
As of v1.0, conversion options are available for:
xsi:type discriminator handlingThe selected options are reflected in the generated OpenAPI v3 contract and applied at runtime.
A Correlation ID is a unique identifier attached to each request as it enters the platform. This ID is propagated through the entire request lifecycle, including runtime conversion, the backend call, the response, and all associated logs and audit entries. It is the primary key for tracing and debugging, allowing you to tie together raw logs, structured runtime logs, and audit trail entries for a single transaction.
Contract Drift occurs when a backend service's response no longer conforms to the schema defined in the contract. The runtime can detect this mismatch and reports it as an explicit signal.
Response-side schema validation can be configured in one of three modes:
off: No validation is performed.monitor: Drift is detected and logged, but the response is still processed.enforce: A response that violates the schema is rejected. The platform returns an HTTP 502 Bad Gateway status with an S2R-VAL-0430 error code, indicating an upstream problem.An Environment is a named deployment target for a service, such as dev, test, or prod. A service can have different backend endpoint URLs and credentials for each environment. Observability data, like traffic metrics and logs, can be filtered by environment.
Mapping versions are environment-agnostic; the same version can be promoted across environments. However, backend connection details are scoped to a specific environment.
The platform uses Role-Based Access Control (RBAC) to manage permissions. Roles can be assigned based on identity provider groups, direct in-app bindings, or an emergency bootstrap list. All changes are recorded in the audit trail. The platform supports identity providers such as Google IAP, Azure AD, and any standard SAML or OIDC provider.
There are three built-in roles:
| Role | Permissions |
|---|---|
| admin | Full control over the platform: onboarding, publishing, configuration, RBAC management, data retention, and all operator actions. |
| operator | Day-to-day operational tasks: onboarding services, configuring mappings, publishing versions, running tests, and managing discovery. Cannot perform platform-level administrative functions. |
| reader | Read-only access: can view services, dashboards, logs, and the audit trail, but cannot make any changes. |
The following diagram illustrates the relationships between the core concepts:
Service (one direction: PUBLISH or CONSUME)
├── Operation(s) ← request/response/fault mapping per operation
│ └── Conversion-option overrides ← field/operation tier
├── Mapping version(s) v1, v2, … ← immutable, one active, rollback any
├── Environment(s) dev / test / prod ← backend endpoint + credentials per env
└── Learned example(s) ← real captured payloads, per operation
Discovery (traffic-driven, via Connectors) ──► populates the service inventory
Correlation ID ──► threads one call across runtime, logs, audit
Contract drift ──► flagged when a backend response stops matching the contract
RBAC roles (admin / operator / reader) ──► gate every action; audited
enforce mode for the operation.502 Bad Gateway status to the client with the error code S2R-VAL-0430. This indicates a problem with the backend service, not the client's request.