SOAP-to-REST Central Conversion Platform Architecture

Overview

The SOAP-to-REST Central Conversion Platform is a no-code solution designed to expose internal SOAP-based backend services as modern REST APIs. It acts as a central conversion layer, simplifying the integration of legacy systems into a RESTful ecosystem.

The platform is an internal-only system. It is designed to sit behind an API gateway (such as Apigee) and an internal load balancer. API consumers interact with the generated REST APIs through the gateway, which forwards requests to the platform's runtime component. The runtime then converts the REST request, calls the appropriate internal SOAP backend, and transforms the SOAP response back into a REST response for the consumer.

API publishers use the platform's administrative interface to manage the conversion process. This involves importing a SOAP service's WSDL file, configuring the backend service URL, and allowing the platform to automatically generate the REST-to-SOAP mappings and an OpenAPI v3 specification for the new REST API.

The platform also provides built-in observability features, including dashboards, debug tracing, and audit logging. It supports versioning and rollback for each configured API service.

How It Works

The platform is composed of separate control plane and data plane services running on Google Cloud Run. The control plane provides the administrative interface for managing APIs, while the data plane handles the live request/response conversions.

Request Flow

At runtime, a request from an API consumer flows through the API gateway and internal load balancer to the platform's runtime service, which then communicates with the backend SOAP service.

flowchart TD
    subgraph "API Consumer VPC"
        A[API Consumer]
    end

    subgraph "API Platform VPC"
        B[API Gateway]
        C[Internal Load Balancer]
        D[SOAP-to-REST Runtime]
    end

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

    A --> B
    B --> C
    C --> D
    D --> E
    E --> D
    D --> C
    C --> B
    B --> A

Platform Components

The system consists of four primary Cloud Run services:

• s2r-admin-ui: The control plane's web-based user interface. API publishers use this interface to import WSDLs, configure services, manage role-based access control, and view observability dashboards.
• s2r-admin-api: The backend API for the control plane. It handles administrative functions such as creating and updating settings, managing role bindings, updating operation policies, and activating or rolling back service versions.
• s2r-runtime: The data plane. This service executes the real-time conversion of REST requests to SOAP and SOAP responses back to REST. It uses a short-lived read cache for route resolution to optimize performance.
• s2r-worker: A service for handling asynchronous background jobs, using technologies like Pub/Sub and Cloud Tasks.

Platform Integration

The platform integrates with the Specaria licensing system. The s2r-runtime service fetches a JSON Web Key Set (JWKS) from api.specaria.io to validate a license JWT. If consented by the customer, the runtime also emits a daily heartbeat containing PII-redacted numeric metrics to the Specaria platform.

Key Constraints

Operators must be aware of the following system-level constraints and design choices:

• Private Network: All components, including the Cloud Run services and the Cloud SQL database, operate on a private network. There are no public endpoints for the Cloud Run services.
• Payload Size Limit: The s2r-runtime service enforces a hard limit of 30 MB for synchronous request payloads. Requests exceeding this limit are rejected.
• Manual Apigee Deployment: The platform generates an OpenAPI specification, but the corresponding API proxy deployment and import into Apigee must be performed manually.
• Database: The platform uses a Cloud SQL for PostgreSQL instance for persistence, with application services authenticating via IAM database authentication.
• IAM Roles: Access to the control plane is managed through Cloud Identity groups mapped to three internal roles: admin, operator, and reader.

Configuration

The platform includes several default runtime policies that are configurable.

Internal Access and Routing

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

The Admin API (s2r-admin-api) supports the following management capabilities. The source does not specify the exact endpoint paths, methods, or request/response schemas for these operations.

• CRUD operations for settings
• CRUD operations for role-bindings
• Updates for operation policies
• Service version activation and rollback
• Observability endpoints

Troubleshooting

Payload Size Exceeded

• Condition: An API consumer sends a request with a payload larger than the 30 MB limit.
• Trigger: The s2r-runtime service receives a request where the body size exceeds 30 MB.
• Result: The service immediately rejects the request with an HTTP 413 Payload Too Large status code.
• Log Signature: This event is logged with result_code=rejected and the error code S2R-RUN-0413.

Deployment Failures

• Condition: A deployment script fails during execution.
• Trigger: The deployment scripts are designed to "fail-fast," meaning they will halt immediately if any external command (e.g., gcloud, terraform) returns an error.
• Result: The deployment process stops, preventing a partial or inconsistent state. Check the script output for the specific command that failed.

Related Documents

The source repository contains further documentation that provides additional context on the platform's design and implementation.

• docs/architecture.md: Target architecture and data flow diagrams.
• docs/decisions.md: A log of 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 details on the payload size limit.
• docs/lld/: Directory containing low-level design documents that serve as the source of truth for implementation names, contracts, and schemas.
• docs/rfc/specaria-platform-integration.md: A document detailing the integration with the Specaria licensing and metrics platform.

All SOAP-to-REST docs