SOAP-to-REST Conversion Platform Architecture

Overview

The SOAP-to-REST Conversion Platform provides a central, no-code solution for exposing internal SOAP-based backend services as modern RESTful APIs. It is designed to run in a private, internal-only network environment on Google Cloud Run.

The platform solves the problem of integrating legacy SOAP services with modern REST-based API consumers without requiring code changes to the backend services. API publishers can import a WSDL file, configure the backend service URL, and the platform automatically generates the REST-to-SOAP mappings and a corresponding OpenAPI v3 specification.

Key capabilities include:

• No-code conversion of SOAP services to REST APIs.
• Automatic generation of OpenAPI v3 documentation for converted services.
• Built-in observability dashboards, debug tracing, and audit logging.
• Versioning and rollback support for each managed API service.
• A separated control plane for administration and data plane for runtime request processing.

The typical data flow involves an API gateway (such as Apigee) routing requests to an internal load balancer, which directs traffic to the platform's runtime service. The runtime service then communicates with the internal SOAP backends over a private network.

How It Works

The platform operates with two distinct planes: a Control Plane for administration and a Data Plane for processing live API traffic.

Control Plane

API publishers interact with the Control Plane via a web interface (s2r-admin-ui) to manage the API lifecycle. The administrative flow is as follows:

1. An administrator imports a WSDL file from a backend SOAP service.
2. They configure the private URL for the target SOAP backend.
3. The platform automatically generates the necessary mappings to translate RESTful HTTP requests into SOAP messages and vice-versa.
4. An OpenAPI v3 specification is generated for the new REST API, which can be used by API consumers.

The Admin UI communicates with a dedicated Admin API (s2r-admin-api), which handles all configuration, policy updates, versioning, and role management. System parameters and role mappings are managed via Parameter Manager.

Data Plane

The Data Plane, or runtime, processes incoming requests from API consumers.

1. A REST API request is sent from an API consumer, typically through an API Gateway like Apigee.
2. An internal HTTP load balancer receives the request and routes it to the s2r-runtime service based on the URL path.
3. The runtime service validates the request, including enforcing a maximum payload size.
4. It uses a short-lived cache to resolve the route and identify the target SOAP backend.
5. The service transforms the incoming REST request into a SOAP XML message using its generated mappings. The transformation is handled by an internal SoapMessageMapper that uses standard javax.xml.transform DOM manipulation.
6. The SOAP request is sent to the backend service over private network connectivity.
7. The runtime service receives the SOAP response, transforms it back into a JSON REST response, and returns it to the original caller.

The following diagram illustrates the request flow for both the data plane and control plane.

flowchart TD
    subgraph "API Consumer"
        direction LR
        A[Client Application]
    end

    subgraph "API Publisher"
        direction LR
        B[Administrator via Browser]
    end

    subgraph "API Platform"
        direction TB
        C[API Gateway / Apigee] --> ILB{Internal HTTP<br>Load Balancer}

        subgraph "Control Plane (Cloud Run)"
            AdminUI[s2r-admin-ui] <--> AdminAPI[s2r-admin-api]
            AdminAPI <--> DB[(Cloud SQL<br>PostgreSQL)]
            AdminAPI <--> Worker[s2r-worker]
        end

        subgraph "Data Plane (Cloud Run)"
            Runtime[s2r-runtime]
        end

        ILB -- / --> AdminUI
        ILB -- /admin/* --> AdminAPI
        ILB -- /worker/* --> Worker
        ILB -- /{dev,test,prod}/* --> Runtime
    end

    subgraph "Backend Services"
        direction LR
        D[Internal SOAP<br>Backend]
    end

    A --> C
    B --> AdminUI
    Runtime --> D

System Architecture

The platform is composed of four primary services deployed on Google Cloud Run, a Cloud SQL database for persistence, and other supporting Google Cloud services.

• s2r-admin-ui: The frontend web application that provides the administrative interface for managing APIs, settings, and roles.
• s2r-admin-api: The backend API for the control plane. It supports CRUD operations for settings, role-bindings, operational policies, and version management, as well as providing observability endpoints.
• s2r-runtime: The data plane service that handles the real-time conversion of REST requests to SOAP and back. It is designed for high-throughput, low-latency processing.
• s2r-worker: A service for handling asynchronous background jobs, triggered via Pub/Sub or Cloud Tasks.

Network and Connectivity

• Ingress: Cloud Run services are configured for internal-and-cloud-load-balancing ingress, accessible only from the project's VPC network and the internal load balancer.
• Egress: Services use Direct VPC egress to communicate with other resources within the VPC, such as the Cloud SQL database and backend SOAP services, without requiring a VPC connector.
• Database: The platform uses a Cloud SQL for PostgreSQL instance with private connectivity. Application services authenticate to the database using Cloud SQL IAM database authentication with dedicated service accounts. A database password is also stored in Secret Manager for break-glass or direct database administrator access.
• Peering: The dedicated GCP project for the platform is expected to use VPC peering to a central project for shared network services.

Platform Access

Access to the platform's services is routed through a regional internal HTTP load balancer. The routing is path-based:

Configuration

The runtime service has several default policies that are configurable. The source does not specify the method for changing these configurations.

Identity and Access Management

The platform's control plane uses a role-based access control (RBAC) model with three predefined roles. These roles are mapped to Cloud Identity groups, which are configured after the initial deployment via the Admin UI or by directly modifying the s2r_role_binding database table.

The roles are:

• Admin (SOAP-To-REST_Admin@<tenant-domain>): Full administrative privileges over the platform.
• Operator (SOAP-To-REST_Oper@<tenant-domain>): Permissions to operate and manage API services, but not system-level settings.
• Reader (SOAP-To-REST_Reader@<tenant-domain>): Read-only access to view configurations and dashboards.

Platform Licensing and Telemetry

The platform integrates with the Specaria licensing system. This has operational implications for network egress and license validation.

• License Validation: At runtime, the s2r-runtime service fetches a JSON Web Key Set (JWKS) from api.specaria.io to validate a license JWT. Network egress must be configured to allow this communication.
• Telemetry: If consented, the platform emits a daily heartbeat to the Specaria platform. This heartbeat contains PII-redacted numeric metrics about platform usage.

Troubleshooting

413 Payload Too Large

The runtime service enforces a hard limit on the size of synchronous request payloads.

• Condition: An API consumer sends a request with a payload exceeding the 30MB limit.
• Result: The s2r-runtime service will immediately reject the request with an HTTP 413 Payload Too Large status code.
• Logging: When a request is rejected for this reason, the platform generates a log entry containing result_code=rejected and a specific error code S2R-RUN-0413. This can be used for monitoring and alerting on payload size issues.

See Also

For more detailed information, API publishers and operators can refer to the following design documents by their subject:

• Target Architecture and Data Flow: Describes the intended system architecture in greater detail.
• Technical Decisions and Tradeoffs: Documents the reasoning behind key technical choices made during development.

All SOAP-to-REST docs