s2r Architecture Overview

Overview

The s2r platform provides a comprehensive solution for converting SOAP services to REST APIs, enabling API publishers to expose legacy SOAP functionalities through modern REST interfaces. It is designed for high performance, scalability, and ease of management, supporting a wide range of SOAP complexities including nested structures and international character sets. The architecture separates control plane functions, such as API definition and management, from data plane functions, which handle live API traffic and transformations. (source: docs/architecture.md)

Key capabilities include:

• Automated API Generation: Streamlined process for importing WSDLs and auto-generating REST resources, OpenAPI specifications, and mappings. (source: docs/architecture.md)
• Robust Runtime Transformation: Efficient conversion of REST calls to SOAP and vice-versa, with support for WS-Security and backend routing. (source: docs/architecture.md)
• Scalable Infrastructure: Leverages Google Cloud services for high availability, performance, and operational resilience. (source: docs/architecture.md)
• No-Code Administration: A user-friendly interface for managing services, versions, and configurations without manual coding. (source: docs/architecture.md)
• Large Payload Handling: Strategies for managing synchronous payloads up to 30MB, with future provisions for larger asynchronous operations. (source: docs/architecture.md)
• Internationalization: Full UTF-8 support across all layers and specific handling for complex character sets like Hebrew. (source: docs/architecture.md)

The platform is ideal for API publishers looking to modernize their SOAP services, integrate with contemporary systems, and improve developer experience by offering RESTful interfaces. (source: docs/architecture.md)

How it Works

The s2r architecture is composed of several high-level components, logically separated into a control plane and a data plane, and deployed with a focus on private network access and security. (source: docs/architecture.md)

High-Level Components

The platform utilizes a suite of Google Cloud services to deliver its functionality:

• Frontend Exposure: Apigee X handles frontend REST exposure, applies policies, and manages API consumer authentication. (source: docs/architecture.md)
• Load Balancing: Internal HTTP Load Balancers direct traffic to Cloud Run services for both the runtime engine and the admin UI, using serverless NEGs. (source: docs/architecture.md)
• Core Services (Cloud Run):
  • Cloud Run Runtime Service: The core engine for REST to SOAP conversion. (source: docs/architecture.md)
  • Cloud Run Admin API Service: Manages WSDL import, CRUD operations, versioning, and publish states. (source: docs/architecture.md)
  • Cloud Run Admin UI Service: Provides the no-code portal, dashboards, and debugging tools. (source: docs/architecture.md)
  • Cloud Run Worker Service / Jobs: Handles heavy asynchronous tasks such as WSDL parsing, code/model generation, spec generation, alert evaluation, and synthetic monitoring. (source: docs/architecture.md)
• Data Storage:
  • Cloud SQL PostgreSQL: Stores metadata, mappings, versions, audit records, debug indexes, SMTP alert history, and synthetic monitor definitions. (source: docs/architecture.md)
  • Cloud Storage: Used for WSDL files, generated OpenAPI specs, mapping artifacts, and staging large payloads. (source: docs/architecture.md)
• Orchestration & Secrets:
  • Pub/Sub + Cloud Tasks: Facilitates background orchestration and retry mechanisms. (source: docs/architecture.md)
  • Secret Manager: Securely stores SOAP credentials, WS-Security materials, and certificates. (source: docs/architecture.md)
  • Parameter Manager: Manages control-plane system parameters and IAM group-role mapping. (source: docs/architecture.md)

Network and Security

The platform operates within a secure, private network environment:

• Project ID: mot-soap-to-rest. (source: docs/architecture.md)
• Cloud Run Ingress: All Cloud Run services are deployed with ingress=internal, meaning access is restricted to internal network traffic. (source: docs/architecture.md)
• Private Access Path: The runtime access path is strictly private, flowing from the Apigee runtime VPC through an internal Load Balancer to Cloud Run. (source: docs/architecture.md)
• Outbound Connectivity: Cloud Run outbound connections use Direct VPC egress with specified network and subnet for private routes. (source: docs/architecture.md)
• Database Access: Cloud SQL is accessed via private IP with IAM database authentication, leveraging service account identities. (source: docs/architecture.md)
• VPC Peering: Project-level VPC peering can be established to a central project as required. (source: docs/architecture.md)
• Resource Reuse: Existing VPC/subnet and a pre-existing Cloud SQL instance (mot-soap-to-rest) are reused. (source: docs/architecture.md)
• No Serverless VPC Connector: The current design does not require a Serverless VPC connector. (source: docs/architecture.md)

Control Plane vs. Data Plane

The architecture distinctly separates administrative functions from runtime operations:

Control Plane (Admin Services)

The control plane is responsible for the setup, configuration, and management of SOAP to REST services. Its functions include:

• WSDL Management: Importing and validating WSDLs, auto-discovering operations and types. (source: docs/architecture.md)
• Mapping Generation: Deterministically generating mappings for request/response wrappers, cardinality, and type coercion from full WSDL/XSD contracts. (source: docs/architecture.md)
• REST API Generation: Auto-generating REST paths and OpenAPI v3 specifications, including schema-aware path parameters and GET-style query parameters inferred from imported request contracts. (source: docs/architecture.md)
• Versioning and Retention: Managing service versions for rollback and defining retention policies for audit and debug logs. (source: docs/architecture.md)
• System Parameters: Managing system parameters via the Parameter Manager. (source: docs/architecture.md)
• Testing and Debugging: Providing a test harness and debug trace viewer. (source: docs/architecture.md)
• Admin UI: Offering a scale-oriented admin user experience for service inventory, bulk actions, and observability drill-down. (source: docs/architecture.md)
• Admin Role Resolution: The s2r-admin-api resolves admin roles from direct principal bindings, forwarded IAP groups, and Cloud Identity group membership lookups when IAP group headers are absent. (source: docs/architecture.md)

Data Plane (Runtime Service)

The data plane handles the execution of live REST API calls and their conversion to SOAP. Its responsibilities include:

• Production Call Handling: Processing incoming production REST calls. (source: docs/architecture.md)
• Transformation: Converting JSON payloads to XML/SOAP and vice-versa. (source: docs/architecture.md)
• Routing: Resolving REST routes (exact and placeholder) and feeding extracted path and query parameters into the SOAP request mapping. (source: docs/architecture.md)
• Security: Applying WS-Security when configured. (source: docs/architecture.md)
• Backend Versioning: Routing to the selected backend version/environment. (source: docs/architecture.md)
• Monitoring: Emitting audit, metrics, and debug events. (source: docs/architecture.md)
• Contract Drift Detection: Emitting explicit backend response-contract drift events if live SOAP payloads no longer match the stored mapping contract. (source: docs/architecture.md)
• Scalability: Running with a minimum of 1 instance and configured for autoscaling. (source: docs/architecture.md)
• Authorization: Does not use IAM-group role mapping for end-user authorization. (source: docs/architecture.md)

Performance Model

The platform is designed for high performance and scalability:

• Target Overhead: Aims for converter overhead of less than 5ms. (source: docs/architecture.md)
• Operational Capacity: Planned to handle approximately 100 configured services and 1 million API calls per day, with burst-oriented capacity validation. (source: docs/architecture.md)
• Runtime Tuning:
  • Runtime services are stateless, with no persistent in-memory business state. (source: docs/architecture.md)
  • All persistent definitions and version state are stored in Cloud SQL. (source: docs/architecture.md)
  • Allows short-lived, non-persistent in-memory read cache for hot mapping metadata. (source: docs/architecture.md)
  • Compiles and caches parsed contract-node metadata in-memory to avoid re-walking raw contract maps on repeated conversions. (source: docs/architecture.md)
  • Utilizes non-blocking I/O and prebuilt serializers. (source: docs/architecture.md)
  • Employs connection pooling for SOAP and Cloud SQL access. (source: docs/architecture.md)
  • Refreshes IAM DB auth tokens safely while the application is running. (source: docs/architecture.md)
  • Emits full logs for errors; payload logging for success paths is only enabled when debug is active. (source: docs/architecture.md)
• Admin/Control-Plane UI Tuning:
  • Prefers server-side pagination, filtering, and sorting to avoid loading all rows. (source: docs/architecture.md)
  • Lazy-loads heavy detail sections and payload viewers. (source: docs/architecture.md)
  • Keeps summary pages free of raw payload tables by default. (source: docs/architecture.md)
  • Uses drill-down flows for transaction-level inspection. (source: docs/architecture.md)

Large Payload Strategy

The platform handles payloads up to a specific synchronous limit:

• Synchronous Mode: Supports payloads up to 30MB. (source: docs/architecture.md)
• Rejection Policy: Payloads exceeding 30MB are rejected with a 413 Payload Too Large error and a structured error body. (source: docs/architecture.md)
• Future Mode: An asynchronous large-object mode for payloads greater than 30MB can be added in the future. (source: docs/architecture.md)

Hebrew and Nested SOAP Support

The platform is designed to handle complex international and SOAP-specific requirements:

• UTF-8 Support: End-to-end UTF-8 support across REST, SOAP, database, and OpenAPI artifacts. (source: docs/architecture.md)
• Binary/File SOAP Operations: Supports attachment-style responses, including MTOM/XOP and MIME multipart. Binary parts can be mapped to contract-aware REST payloads, and binary-root responses can be streamed as direct REST file downloads. (source: docs/architecture.md)
• SOAP Coverage Boundaries:
  • Asynchronous SOAP/callback support exists in runtime/admin persistence but onboarding configuration and admin workflow are incomplete. (source: docs/architecture.md)
  • Broader WS-Security variants beyond the current baseline are pending. (source: docs/architecture.md)
  • SOAP-encoded/legacy RPC support is partial, though common href/multiRef response indirection and SOAP-encoded array semantics are resolved during parsing. (source: docs/architecture.md)
  • Namespace repair includes preview, manual prefix mapping, repaired-XML import, external-reference diagnostics, downloadable reports, and ZIP export for multi-file contracts, but not yet a full admin repair toolkit. (source: docs/architecture.md)
• Right-to-Left Text: Preserves right-to-left text as data, with UI controls handling rendering direction. (source: docs/architecture.md)
• Nested XSD Structures: Supports deep nested XSD structures, repeated arrays, and xsi:nil. (source: docs/architecture.md)
• Fault Mapping: Provides fault mapping for SOAP Faults to a consistent REST error model. (source: docs/architecture.md)

No-Code Admin Flow

The s2r platform provides a no-code administrative flow for onboarding and managing SOAP services, primarily through the WSDL Onboarding UI. (source: docs/architecture.md)

The typical workflow for an API publisher is as follows:

1. Upload WSDL: The API publisher uploads a WSDL file or provides a WSDL URL. (source: docs/architecture.md)
2. Parse Operations and Schemas: The system parses the WSDL to identify operations and schemas. (source: docs/architecture.md)
3. Auto-generate Onboarding Review: The system automatically generates a review summary, including:
   • Inferred backend endpoint suggestions from WSDL service/port/soap:address. (source: docs/architecture.md)
   • Draft generation suggestions (serviceKey, serviceName, default dev environment). (source: docs/architecture.md)
   • Suggested REST method/path preview per operation, including route provenance, example URL/body, and collision visibility. (source: docs/architecture.md)
   • Route fallback/collision counters in the import summary. (source: docs/architecture.md)
   • Inferred resource-group plus path/query-parameter candidate preview per operation. (source: docs/architecture.md)
   • Generated SOAP request/response envelope previews from onboarding sample payloads. (source: docs/architecture.md)
   • Zero-touch readiness summary per import. (source: docs/architecture.md)
   • Re-import diff against the latest comparable WSDL artifact. (source: docs/architecture.md)
   • Generated request/response sample payloads per operation. (source: docs/architecture.md)
   • Contract complexity hints for choice, wildcard, union/list, attributes, and polymorphic variants. (source: docs/architecture.md)
4. Auto-generate Initial REST Resources:
   • Path and method are heuristically inferred from the SOAP operation name (e.g., get/list/create/update/delete/...) with collision fallback, and remain editable. (source: docs/architecture.md)
   • For read/update/delete patterns, generated path placeholders prefer a matched request-schema field name (e.g., {citizenId}) when a clear candidate is available in the imported contract. (source: docs/architecture.md)
5. Configure Backend Endpoint and Auth Profile: The API publisher configures the backend SOAP endpoint and authentication profile. (source: docs/architecture.md)
6. Auto-create Mappings: The system automatically creates request, response, and fault mappings. The current baseline is generic auto mapping. (source: docs/architecture.md)
7. Optional One-Click Zero-Touch Autopilot: An optional feature to immediately create a draft from the WSDL using inferred service identity and backend defaults, returning the first publish-readiness assessment. Batch zero-touch onboarding from multiple WSDLs/URLs is also supported. (source: docs/architecture.md)
8. Run Test Call: The API publisher can run a test call with a generated sample payload or draft-wide generated smoke tests. (source: docs/architecture.md)
9. Refresh Publish Readiness Gate: The system provides a publish readiness assessment based on backend/test/mapping/WSDL comparison signals, suggesting remediation actions. This includes carrying route fallback/collision counts from the import review into warnings. (source: docs/architecture.md)
10. Refresh Version-Level WSDL Drift Watch: From the Services UI, the API publisher can compare the tracked version artifact against the newest imported contract. (source: docs/architecture.md)
11. Save as Version and Activate: The configuration can be saved as a new version (vN) and set as active once readiness is not blocked. (source: docs/architecture.md)
12. Export OpenAPI v3 File: The system exports an OpenAPI v3 file for manual import into Apigee. This export includes generated path parameters, GET-style query parameters, JSON body field bindings, example URL/body extensions, and preserves WSDL/XSD scalar constraints (e.g., enum, pattern, length, numeric bounds) into generated OpenAPI schemas. Escaped Hebrew regex forms are normalized to literal Hebrew letters. (source: docs/architecture.md)

    {
      "paths": {
        "/myService/myOperation/{citizenId}": {
          "get": {
            "parameters": [
              {
                "name": "citizenId",
                "in": "path",
                "required": true,
                "schema": {
                  "type": "string",
                  "pattern": "^[א-ת ]+$"
                },
                "description": "Citizen ID for the operation"
              }
            ],
            "summary": "Example operation with Hebrew regex pattern"
          }
        }
      }
    }
    

    (source: docs/architecture.md)
13. Run Connection/Auth Diagnostics: Diagnostics for SOAP endpoints, including WSDL pull checks, can be run. (source: docs/architecture.md)

Configuration and Parameters

The s2r platform provides several configurable parameters and operational defaults. (source: docs/architecture.md)

Name	Type	Default	Description

---

All SOAP-to-REST docs