Loading…
Loading…
Understand the core concepts of the API platform, including services, operations, mappings, and the Publish/Consume model for SOAP-to-REST transformation.
This document defines the core concepts and vocabulary used throughout the platform. Understanding these terms is essential for operating the system, as they map directly to UI labels, API resources, and database tables (prefixed with s2r_).
NOTE
All concepts described here have been part of the General Availability (GA) product since v1.0.
The platform is designed to manage and execute integrations between SOAP and REST services. The following concepts represent the fundamental building blocks you will use to configure, deploy, and monitor these integrations. Each concept represents a specific entity or process within the platform's architecture.
A Service is the central organizing unit. It is composed of Operations, versioned with Mapping Versions, and deployed across Environments. The diagram below illustrates the primary compositional relationships. Other concepts like Discovery, Correlation ID, and Contract Drift relate to the broader operational lifecycle.
graph TD
Service -- "has one" --> Direction["Direction (Publish/Consume)"]
Service -- "has one or more" --> Operation
Service -- "has one or more" --> MappingVersion["Mapping Version"]
Service -- "has one or more" --> Environment
Operation -- "can have" --> LearnedExample["Learned Example"]
Operation -- "can have" --> ConversionOverrides["Conversion Option Overrides"]A Service is the primary unit of integration, representing a single onboarded SOAP or REST backend. It is the entity that you publish, version, and observe. Each service has:
serviceKey.Publish or Consume).An Operation represents a single callable action within a Service. It corresponds to a WSDL operation (e.g., GetCustomer) that is exposed as a REST endpoint (e.g., GET /customers/{id}) in the Publish direction. Most configuration details, including request/response mappings, fault handling, validation, and Conversion Option overrides, are defined at the operation level.
A Mapping is the deterministic, rule-based translation between a SOAP message structure and a REST/JSON structure for a specific operation. The platform generates this mapping from the service contract (WSDL/XSD or OpenAPI). This "full-field mapping" covers the entire request and response data tree, including all elements, attributes, optional fields, and declared faults. The process is deterministic, meaning the same contract always produces the same mapping. While there is no manual transformation language, you can apply field-level overrides to adjust the default behavior for specific business rules.
Mappings are stored as immutable, versioned snapshots (e.g., v1, v2). Once created, a mapping version cannot be changed. To deploy a mapping, you activate a specific version to handle live traffic. This model allows for safe, one-click rollbacks to any previous version. When you import an updated service contract, the platform creates a new mapping version and provides a change report detailing added or removed operations, breaking changes, and per-operation deltas, rather than modifying the active version in place.
Every service operates in one of two directions:
PUBLISH: Exposes a SOAP backend as a modern REST API.
CONSUME: Exposes a modern REST backend as a legacy SOAP service.
none, basic, bearer, OAuth2 client-credentials, API-key header, and mutual TLS.Discovery is the process of automatically identifying SOAP services by observing live traffic at the network edge, eliminating the need to manually locate and upload WSDL files. Discovered services are listed in a central view with request counts over 24-hour, 7-day, and 1-month periods. These metrics are served from pre-computed aggregation tables for fast query performance. Consumer attribution is determined using headers such as X-Client-IP, X-Forwarded-For, or Forwarded.
A Connector is an integration that enables the platform to discover services and ingest traffic from a specific edge device or API gateway. The platform ships with connectors for a variety of products:
A Learned Example is a real request/response payload, including headers, captured from live production traffic for 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 generated by a worker process from the raw traffic ingest feed.
A Conversion Option is a tunable setting that controls the behavior of the SOAP-to-REST transformation. Options can be set globally as platform-wide defaults and can be overridden at the service, operation, or individual field level. The resolution hierarchy is: field > operation > service > platform default.
As of v1.0, available options control:
xsi:type discriminator handlingThe selected options are reflected in the generated OpenAPI v3 contract and are enforced by the runtime.
A Correlation ID is a unique identifier attached to each request at the start of its lifecycle. It is propagated through all stages, including runtime conversion, backend calls, responses, logs, and audit trails. This ID is the primary key for tracing and diagnostics, linking raw logs, structured runtime logs, and audit entries for a single transaction.
Contract Drift occurs when a backend service's actual response deviates from the contract (schema) expected by the platform for an operation. The runtime detects this mismatch and flags 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. This triggers an S2R-VAL-0430 error, and the platform returns an HTTP 502 Bad Gateway to the original caller, indicating an upstream problem.Platform access is managed through Role-Based Access Control (RBAC), with three predefined roles. Roles can be mapped from an identity provider's groups, direct principal bindings, or an emergency bootstrap list. Supported identity providers include Google IAP, Azure AD, and any standard SAML or OIDC provider. All changes are recorded in the audit trail.
| Role | Permissions |
|---|---|
| admin | Full control: onboarding, publishing, configuration, RBAC management, data retention, and all operator actions. |
| operator | Day-to-day operations: onboarding, configuration, publishing, versioning, testing, and discovery management. No platform-level admin functions. |
| reader | Read-only access: view services, dashboards, logs, and audit trails. No changes are permitted. |
An Environment is a named deployment target, such as dev, test, or prod. A service can have distinct backend endpoint URLs and credentials for each environment. The platform's observability and traffic monitoring surfaces use the environment as a primary dimension for filtering and analysis. Mapping versions are environment-agnostic and can be promoted across environments, while connection details remain specific to each environment.
enforce mode.S2R-VAL-0430 and returns an HTTP 502 Bad Gateway status to the client, signaling that the error originated in an upstream system, not with the client's request.