Introduction

An overview of SOAP-2-REST (S2R), a platform that converts between SOAP and REST to bridge legacy and modern services within your own VPC.

Introduction to SOAP-2-REST by Specaria (S2R)

SOAP-2-REST by Specaria (also known as Specaria S2R) is a service that converts between SOAP and REST protocols in both directions. It is designed to run inside your own VPC, alongside your existing API gateway and SOAP services, providing a bridge between legacy systems and modern API consumers.

The platform solves the common challenge of integrating modern REST-based clients (such as mobile apps, partner integrations, and AI agents) with established SOAP-based services. It also enables legacy SOAP clients to continue functioning even after a backend service has been migrated to REST.

Key capabilities include:

Deterministic, full-field mapping generated directly from service contracts (WSDL or OpenAPI), ensuring every element, attribute, and optional field is covered without requiring a proprietary transformation language.
Bidirectional conversion, allowing you to expose SOAP backends as REST APIs or REST backends as SOAP services.
In-app observability, with features like log search by correlation ID.
Immutable, versioned mappings with one-click rollback.
Field-level overrides available through a user interface for handling specific business rules.

The product is at General Availability (GA) as of version 1.0.

How it Works

S2R operates on a "Publish/Consume" model, with both conversion directions handled by the same runtime. The direction is a property configured for each service.

The Publish/Consume Model

Publish: REST Facade over a SOAP Backend

In the Publish direction, S2R exposes a legacy SOAP service as a modern REST/JSON API.

A REST/JSON API consumer calls a REST endpoint generated by S2R.
The S2R runtime converts the inbound REST request to a SOAP message.
The runtime calls the existing backend SOAP service.
The runtime converts the SOAP response from the backend into a JSON response and returns it to the consumer.

Inbound Contract: OpenAPI v3 (generated per service)
Backend: Your existing SOAP service (unchanged)
Use Case: Expose a legacy SOAP estate as clean REST APIs for new consumers.

Consume: SOAP Facade over a REST Backend

In the Consume direction, S2R allows a legacy SOAP client to communicate with a backend that has been modernized to REST.

A legacy SOAP client sends a SOAP request to an endpoint managed by S2R.
The S2R runtime accepts the SOAP call and converts it to a REST/JSON request.
The runtime calls the migrated REST backend service.
The runtime wraps the REST response into a SOAP envelope and returns it to the SOAP client.

Inbound Contract: WSDL (served by S2R at the consume endpoint)
Backend: Your migrated REST service
Use Case: Maintain compatibility for legacy SOAP clients while modernizing backend services.

NOTE

S2R supports both SOAP 1.1 and SOAP 1.2. As of v1.0, the runtime automatically detects the SOAP version from the message body and content type.

System Architecture

S2R is designed to integrate into your existing environment without replacing major components like your API gateway or load balancer.

Placement in Your Stack

S2R sits alongside your gateway, which continues to handle authentication, rate-limiting, traffic management, and WAF duties. The platform can listen to gateway-edge traffic for service discovery and handles the protocol conversion for production traffic.

The following diagram illustrates the data flow:

flowchart TD
    A[SOAP Estate] --> B[Gateway Edge<br/>F5 / DataPower / Load Balancer];
    B --> C[SOAP-2-REST by Specaria<br/>(runs in your VPC)];
    C --> D[REST Consumers<br/>Mobile apps, partner integrations, SDKs, AI agents];

IMPORTANT

The platform is designed for internal-only deployment and has no public endpoint. Access is managed through your own network and gateway. Backend credentials are encrypted at rest and are never logged or returned in plaintext.

Platform Components

The S2R platform consists of several services that share a single PostgreSQL database for configuration and state. The control plane (for management) and data plane (for traffic) are separate to ensure that operator activity does not impact production traffic.

Component	Role
Admin API (control plane)	Handles WSDL/OpenAPI import, service CRUD operations, mapping generation, versioning, and managing publish state.
Runtime (data plane)	Handles production calls. Converts SOAP↔REST, routes requests to the backend, and emits metrics and audit events.
Worker	Runs background jobs, including discovery aggregation, learned-example curation, spec generation, and alert evaluation.
Admin UI	Provides a no-code portal for operators. Features include an onboarding wizard, dashboards, log search, and audit trail.
PostgreSQL	Acts as the source of truth for all metadata, mappings, versions, audit logs, and aggregation tables. S2R tables are prefixed with `s2r_`.

Target Audience

This documentation is for the technical teams who operate the S2R platform:

Integration Engineers / Architects: Responsible for onboarding services, configuring backends, tuning conversion options, and reviewing generated contracts.
Platform Engineering / SRE Teams: Responsible for deploying the stack, monitoring dashboards and SLOs, searching logs, and responding to events like contract drift.
Security / Identity Teams: Responsible for configuring RBAC and SSO (e.g., IAP, Azure AD, SAML, OIDC) and managing credential encryption and retention policies.