Conversion Platform Architecture

Overview

The SOAP-to-REST Conversion Platform is a no-code solution for exposing internal SOAP-based backend services as modern RESTful APIs. It acts as a centralized conversion layer, abstracting the complexity of SOAP protocols from API consumers.

The platform is designed to operate entirely within a private network environment. It receives REST requests from an API gateway (such as Apigee), translates them into SOAP requests for legacy backend services, and then transforms the SOAP responses back into RESTful JSON responses for the consumer.

The system is composed of two primary logical parts:

• Control Plane: A set of services (s2r-admin-ui, s2r-admin-api, s2r-worker) that provide a user interface and API for API publishers to configure and manage the API conversions. This includes importing WSDL files, mapping to backend services, generating OpenAPI v3 specifications, and managing versions.
• Data Plane: The core s2r-runtime service that performs the live request and response transformations between REST and SOAP. It is built for high-throughput, low-latency processing.

This platform enables API publishers to rapidly create and deploy REST interfaces for existing SOAP services without writing integration code, while providing built-in observability, versioning, and policy enforcement.

Architecture

The platform is deployed as a set of containerized services on Google Cloud Run within a dedicated GCP project. It relies on private network connectivity for all operations, ensuring that neither the platform itself nor the backend SOAP services are exposed to the public internet.

Components

The platform consists of four distinct Cloud Run services:

Runtime Data Flow

The primary function of the platform is to process live API traffic. The data flow for a typical request is as follows:

1. An API consumer sends a REST request to an endpoint managed by an API gateway (e.g., Apigee).
2. The gateway forwards the request to an internal regional HTTP load balancer.
3. The load balancer routes the request to the s2r-runtime service based on the request path.
4. The s2r-runtime service validates the request, including checking the payload size. It uses a short-lived cache for route resolution.
5. The service transforms the incoming REST request into a corresponding SOAP message.
6. The SOAP request is sent to the configured internal backend SOAP service over private network connectivity.
7. The backend service processes the request and returns a SOAP response.
8. The s2r-runtime service transforms the SOAP response back into a RESTful JSON response.
9. The REST response is returned through the load balancer and API gateway to the original consumer.

flowchart TD
    subgraph "API Consumer's Network"
        A[API Consumer]
    end

    subgraph "API Management Layer"
        B[API Gateway / Apigee]
    end

    subgraph "Platform VPC"
        C[Internal Load Balancer]
        D[SOAP-to-REST Runtime<br>(s2r-runtime)]
    end

    subgraph "Backend Services VPC"
        E[Internal SOAP Backend]
    end

    A --> B
    B --> C
    C --> D
    D --"SOAP Request"--> E
    E --"SOAP Response"--> D
    D --"REST Response"--> C
    C --> B
    B --> A

Control Plane and Configuration

API publishers manage the platform's configuration through the control plane. The administrative flow involves:

1. Importing a WSDL file from a backend SOAP service.
2. Configuring the backend service URL.
3. The platform automatically generates REST-to-SOAP mappings.
4. An OpenAPI v3 specification is generated for the new REST API.
5. The configuration is versioned, allowing for activation of new versions or rollback to previous ones.

License and Platform Integration

The platform integrates with the Specaria licensing system. This is a mandatory component for the runtime to function.

• License Validation: The s2r-runtime service fetches a JSON Web Key Set (JWKS) from api.specaria.io. It uses this key set to validate a license JWT during its operation.
• Usage Reporting: With consent, the runtime emits a daily heartbeat to the Specaria platform. This heartbeat contains PII-redacted numeric metrics for usage and billing purposes. Egress to api.specaria.io must be enabled in the VPC's network configuration.

Configuration and Management

Platform behavior is controlled through a combination of runtime policies, access control roles, and system parameters.

Runtime Policies

The s2r-runtime service adheres to several default policies, which are configurable.

Access Control

Access to the control plane is managed via IAM-based roles. These roles are mapped from Cloud Identity groups, which are configured on a per-tenant basis.

Role bindings can be managed via the Admin UI or by directly modifying the s2r_role_binding table in the application database.

API and Endpoint Routing

All services are accessed through a single regional internal HTTP load balancer. The load balancer uses path-based routing to direct traffic to the appropriate Cloud Run service.

Operational Constraints

• Payload Size Limit: The platform enforces a hard limit of 30 MB for synchronous request payloads processed by the s2r-runtime service.
• Autoscaling: The s2r-runtime service is configured with a minimum of 1 instance and scales automatically based on traffic.
• Networking: The platform uses Direct VPC egress and requires VPC peering to a central project for shared network services. It does not use a Serverless VPC Access connector.
• Database: The system uses a Cloud SQL for PostgreSQL instance with private connectivity. Application services authenticate to the database using IAM service accounts.

Troubleshooting

Payload Too Large

• Condition: A client sends a request to the s2r-runtime service with a payload larger than 30 MB.
• Result: The service immediately rejects the request with an HTTP 413 Payload Too Large status code.
• Logging: The event is recorded in Cloud Logging with result_code=rejected and a specific internal error code S2R-RUN-0413. This allows for precise monitoring and alerting on payload size violations.

See Also

The source repository contains further detailed design and planning documentation:

• docs/architecture.md: Target architecture and data flow diagrams.
• docs/decisions.md: A log of key technical decisions and their trade-offs.
• docs/plan.md: The phased implementation plan for the platform.
• docs/backlog.md: The prioritized feature backlog and acceptance criteria.
• docs/questions.md: A list of open questions and resolved decision gates, including the payload size limit.
• docs/lld/: Low-level design documents containing implementation names, contracts, and database schema.

All SOAP-to-REST docs