s2r Architecture Overview

Overview

The s2r platform provides a mechanism for converting SOAP services into RESTful APIs, facilitating the exposure of legacy SOAP functionalities through modern REST interfaces. It addresses the problem of integrating SOAP-based backends with REST-oriented consumers by handling the transformation, mapping, and lifecycle management of these services.

The system is composed of several key components that interact to provide both runtime (data plane) and administrative (control plane) functionalities (source: 1) High-Level Components, 3) Control Plane vs Data Plane).

Key Components:

• Frontend REST Exposure: Apigee X handles external REST exposure, policies, and consumer authentication (source: 1) High-Level Components).
• Load Balancing: Internal Application Load Balancers direct traffic to Cloud Run services for both runtime and administrative functions (source: 1) High-Level Components).
• Core Services:
• Cloud Run Runtime Service: Performs REST to SOAP conversion for production calls (source: 1) High-Level Components).
• Cloud Run Admin API Service: Manages WSDL import, CRUD operations, versioning, and publish states (source: 1) High-Level Components).
• Cloud Run Admin UI Service: Provides a no-code portal for administration, dashboards, and debugging (source: 1) High-Level Components).
• Cloud Run Worker Service / Jobs: Handles asynchronous tasks like WSDL parsing, code/model generation, spec generation, alert evaluation, and synthetic monitoring (source: 1) High-Level Components).
• Persistence: Cloud SQL PostgreSQL stores metadata, mappings, versions, audit records, debug indexes, SMTP alert history, and synthetic monitor definitions (source: 1) High-Level Components).
• Storage: Cloud Storage is used for WSDL files, generated OpenAPI specs, mapping artifacts, and staging large payloads (source: 1) High-Level Components).
• Orchestration: Pub/Sub + Cloud Tasks manage background orchestration and retry mechanisms (source: 1) High-Level Components).
• Secrets Management: Secret Manager stores sensitive information like SOAP credentials, WS-Security materials, and certificates (source: 1) High-Level Components).
• Parameter Management: Parameter Manager handles control-plane system parameters and IAM group-role mappings (source: 1) High-Level Components).

Inputs: WSDL files (for control plane), REST API calls (for data plane) (source: 4) No-Code Admin Flow, 3) Control Plane vs Data Plane). Outputs: REST API responses, OpenAPI v3 specifications, audit/metrics/debug events (source: 3) Control Plane vs Data Plane, 4) No-Code Admin Flow). Callers: API publishers interact with the Admin UI/API, while API consumers interact with the exposed REST endpoints (source: 3) Control Plane vs Data Plane, 4) No-Code Admin Flow).

How It Works

The s2r platform operates through a separation of concerns between its control plane and data plane, orchestrated by various Cloud services (source: 3) Control Plane vs Data Plane).

Control Plane Mechanism

The control plane is responsible for managing the lifecycle of SOAP services exposed as REST APIs. This involves several steps, typically initiated by an API publisher through the Admin UI or Admin API (source: 3) Control Plane vs Data Plane, 4) No-Code Admin Flow).

1. WSDL Import and Validation: A WSDL file is uploaded or provided via URL. The Cloud Run Worker Service parses the WSDL, auto-discovers operations and types, and performs validation (source: 3) Control Plane vs Data Plane, 4) No-Code Admin Flow).
2. Mapping Generation: The system generates deterministic mappings for request/response wrappers, cardinality, and type coercion from the full WSDL/XSD contract. This includes inferring backend endpoint suggestions, draft generation suggestions (serviceKey, serviceName, default dev environment), and suggested REST method/path previews per operation (source: 3) Control Plane vs Data Plane, 4) No-Code Admin Flow).
3. REST Resource Generation: Initial REST resources are auto-generated. Paths and methods are inferred heuristically from SOAP operation names (e.g., get/list/create/update/delete) with collision fallback. Path placeholders prefer matched request-schema field names (e.g., {citizenId}) when a clear candidate is present in the imported contract (source: 4) No-Code Admin Flow).
4. OpenAPI v3 Generation: OpenAPI v3 specifications are auto-generated, including schema-aware path parameters and GET-style query parameters inferred from imported request contracts. WSDL/XSD scalar constraints (e.g., enum, pattern, length, numeric bounds) are preserved into the generated OpenAPI schemas (source: 3) Control Plane vs Data Plane, 4) No-Code Admin Flow).
5. Version Management: The platform supports version management and rollback for services. After configuration and testing, a service can be saved as a version (vN) and set as active when readiness is not blocked (source: 3) Control Plane vs Data Plane, 4) No-Code Admin Flow).
6. Configuration and Testing: API publishers configure backend endpoints and authentication profiles. The system allows running test calls with generated sample payloads or draft-wide smoke tests. Publish readiness gates provide signals for backend/test/mapping/WSDL comparisons and suggest remediation actions (source: 4) No-Code Admin Flow).
7. Persistence: All persistent definitions, version states, metadata, mappings, and audit records are stored in Cloud SQL PostgreSQL (source: 1) High-Level Components, 6) Performance Model). WSDL files, generated OpenAPI specs, and mapping artifacts are stored in Cloud Storage (source: 1) High-Level Components).

Data Plane Mechanism

The data plane handles production REST calls and their conversion to SOAP, and vice-versa (source: 3) Control Plane vs Data Plane).

1. REST Call Handling: The Cloud Run Runtime Service receives production REST calls (source: 3) Control Plane vs Data Plane).
2. Transformation: It transforms JSON requests into XML/SOAP and XML/SOAP responses back into JSON (source: 3) Control Plane vs Data Plane).
3. Route Resolution: The service resolves exact and placeholder REST routes, feeding extracted path parameters and query parameters into the SOAP request mapping (source: 3) Control Plane vs Data Plane).
4. Security: WS-Security is applied when configured (source: 3) Control Plane vs Data Plane).
5. Backend Routing: Calls are routed to the selected backend version/environment (source: 3) Control Plane vs Data Plane).
6. Event Emission: The runtime service emits audit, metrics, and debug events. It also emits explicit backend response-contract drift events if live SOAP payloads no longer match the stored mapping contract (source: 3) Control Plane vs Data Plane).
7. Scaling: The Cloud Run Runtime Service runs with a minimum of 1 instance and is configured to autoscale out (source: 3) Control Plane vs Data Plane). Runtime services are stateless, with persistent state stored in Cloud SQL. Short-lived, non-persistent in-memory read caches are used for hot mapping metadata, and parsed contract-node metadata is compiled/cached in-memory to optimize repeated conversions (source: 6) Performance Model).

Network and Security

Cloud Run services are deployed with ingress=internal, meaning access is private only: Apigee runtime VPC -> internal LB -> Cloud Run. Cloud Run outbound traffic uses Direct VPC egress to private routes. Cloud SQL access is via private IP with IAM database authentication using service account identity. Project-level VPC peering can be configured to a central project (source: 2) Network and Security).

No-Code Admin Flow Example

An API publisher can onboard a SOAP service as a REST API using the following step-by-step process via the Admin UI (source: 4) No-Code Admin Flow):

1. Upload WSDL: The publisher uploads a WSDL file or provides a WSDL URL.
2. Parse Operations and Schemas: The system automatically parses the WSDL to identify operations and schemas.
3. Review Onboarding Suggestions: The system presents an onboarding review, including:

• Inferred backend endpoint suggestions from the WSDL's service/port/soap:address.
• Draft generation suggestions (serviceKey, serviceName, default dev environment).
• Suggested REST method/path previews per operation, showing route provenance, example URL/body, and collision fallback visibility.
• Route fallback/collision counters in the import summary to highlight non-clean REST route plans.
• Inferred resource-group plus path/query-parameter candidate previews per operation.
• Generated SOAP request/response envelope previews from sample payloads.
• A zero-touch readiness summary and re-import diff against the latest comparable WSDL.
• Contract complexity hints for choice, wildcard, union/list, attributes, and polymorphic variants.

4. Auto-generate Initial REST Resources: Based on the review, the system automatically generates initial REST resources. Paths and methods are inferred heuristically from SOAP operation names (e.g., get/list/create/update/delete) and are editable. For read/update/delete patterns, path placeholders prefer matched request-schema field names (e.g., {citizenId}).
5. Configure Backend Endpoint and Auth Profile: The publisher configures the specific backend endpoint URL and authentication profile for the SOAP service.
6. Auto-create Mappings: The system automatically creates request, response, and fault mappings. The current baseline uses generic auto-mapping.
7. Optional Zero-Touch Autopilot: The publisher can use a one-click zero-touch autopilot to immediately create a draft from the WSDL, using inferred service identity and backend defaults. This returns the first publish-readiness assessment. Batch onboarding from multiple WSDL URLs or files is also supported, providing per-item success/error and readiness results.
8. Run Test Call: The publisher runs a test call using a generated sample payload or draft-wide generated smoke tests.
9. Refresh Publish Readiness Gate: The system refreshes the publish readiness gate, providing signals for backend/test/mapping/WSDL comparisons and suggesting remediation actions. This includes route fallback/collision counts as warnings.
10. Refresh Version-Level WSDL Drift Watch: From the Services UI, the publisher can compare the tracked version artifact against the newest imported contract.
11. Save as Version: The configuration is saved as a new version (vN) and can be set as active if readiness is not blocked.
12. Export OpenAPI v3 File: An OpenAPI v3 file is exported for manual import into Apigee. This export includes generated path parameters, GET-style query parameters, and JSON body field bindings derived from the inferred REST route and imported request schema, along with example URL/body extensions. WSDL/XSD scalar constraints are preserved, and escaped Hebrew regex forms are normalized (source: 4) No-Code Admin Flow).
13. Run Diagnostics: Connection/auth diagnostics for SOAP endpoints, including WSDL pull checks, can be run.

Configuration and Parameter Reference

This section details configurable parameters and operational defaults within the s2r platform.

| Name | Type | Default | Required | Description ---

---

All SOAP-to-REST docs