Loading…
Loading…
Find answers to common questions about deployment, SOAP/XSD support, security, data residency, and troubleshooting for the SOAP-to-REST platform.
This document provides answers to frequently asked questions about the SOAP-to-REST platform, intended for engineers who operate the system. The information is based on the General Availability product (v1.0 and later).
The SOAP-to-REST platform is a purpose-built component that converts API traffic between SOAP and REST protocols. It is not a replacement for an API gateway; instead, it complements existing gateways by sitting alongside them within your VPC. Your API gateway continues to manage authentication, rate-limiting, and traffic management, while this platform handles the protocol transformation.
The platform operates in two distinct directions:
A single service instance is configured to operate in exactly one direction. The platform has no public endpoint and all data processing occurs within your infrastructure.
The platform generates a deterministic, full-field mapping from a source API contract (WSDL or OpenAPI) without requiring proprietary transformation languages or per-service scripting. This automatic mapping covers every element, attribute, and optional field. For specific business rules, you can override the conversion behavior on a field-by-field basis.
The runtime automatically detects and supports both SOAP 1.1 and SOAP 1.2, including the application/soap+xml content type and two-level fault model of SOAP 1.2.
Supported message styles include:
The platform provides comprehensive support for XSD features, including:
sequence, choice, allimport, include, and redefine directives (with cycle protection)xsi:type polymorphismlist and union typesany and anyTypeWARNING
RPC/encoded (SOAP section-5) style is intentionally not supported as it is a retired format deprecated by WS-I Basic Profile 1.0. The platform will surface a structured warning (S2R-ADM-0424) during import and the runtime will return a coded error (S2R-RUN-0415) rather than attempting to decode such a message.
SOAP faults are normalized into a deterministic REST error structure. The generated OpenAPI contract reflects any fault detail contracts declared in the source WSDL. You can optionally configure the error shape to conform to RFC 7807 Problem Details.
Numerous aspects of the conversion can be customized via conversion options, which can be set globally and overridden per service, per operation, or per field. These options include:
xsi:type discriminator handlingThe generated OpenAPI v3 contract is standards-compliant and compatible with common developer portals, SDK generators, and AI agent toolchains.
Instead of requiring manual WSDL uploads for every service, the platform can learn your service inventory from live traffic. A connector integrates with your API gateway or load balancer to analyze traffic logs. A generic-HTTP receiver is also available for any edge device that can emit accessible HTTP traffic logs.
The master discovery view displays request counts for each service over 24-hour, 7-day, and 1-month periods, with data loaded from pre-computed aggregation tables for fast performance.
As of v1.0, connectors are available for the following load balancers and API gateways:
The discovery process can capture learned examples: real request/response payloads and headers from production traffic. These are curated against a service and operation to provide consumers with realistic examples instead of synthetic placeholders.
For rapid onboarding, the zero-touch autopilot feature can generate a draft service, its operations, and all mappings in a single step, providing a per-operation readiness score.
The platform can be deployed using one of the following methods, all running within your VPC:
| Dependency | Requirement |
|---|---|
| Database | PostgreSQL (validated against version 16). The database must use UTF-8 encoding. The pgcrypto extension is required. All platform tables are prefixed with s2r_. |
| Java | No host installation is needed. A Java 25 JVM is bundled within the container images. A host JDK is only required if you build the images from source. |
| Parameter | Default Value | Description |
|---|---|---|
| Capacity Baseline | ~1M calls/day | Load-tested for approximately 12 requests/second sustained and 100 requests/second burst. |
| Max Payload Size | 30 MB | Synchronous payloads larger than this are rejected with HTTP 413 and error code S2R-RUN-0413. |
| Operation Timeout | 100 ms | The default timeout for backend calls. This is configurable. |
| Retries | 2 | The default number of retries for backend calls. This is configurable. |
All data, including SOAP traffic, request/response payloads, archives, and learned examples, remains within your VPC. The metadata database also resides in your infrastructure. The product has no public endpoint.
Access is managed via Role-Based Access Control (RBAC) with three built-in roles: admin, operator, and reader. Roles can be mapped from your identity provider's groups (via Google IAP, Azure AD, SAML, or OIDC), direct in-app bindings, or an emergency bootstrap list. All changes are recorded in the audit trail.
Backend credentials are encrypted at rest in the database using the pgcrypto PostgreSQL extension. They are never logged or returned in plaintext.
IMPORTANT
The encryption key is specified by the S2R_CREDENTIAL_KEY environment variable. This key must remain stable. Regenerating it will invalidate all existing encrypted credentials in the database.
By default, data is retained for 60 days. This retention period is configurable.
The platform is not designed for fully air-gapped operation at v1.0. It requires outbound HTTPS connectivity to the Specaria platform for license verification and update notifications.
S2R- error code in the response.| Error Code(s) | Symptom | Cause & Resolution |
|---|---|---|
S2R-RUN-0405 | Requests fail with HTTP 400. | The URL path is missing the required direction segment. Runtime paths must be prefixed with /publish/ or /consume/, e.g., /<direction>/<env>/<serviceKey>/.... |
S2R-VAL-0430 | A successful call returns an unexpected or malformed payload. | The backend service's contract may have changed (contract drift). If response-side validation is in enforce mode, a non-compliant backend response is rejected with HTTP 502 and this error. Check the validation mode (off, monitor, enforce). |
S2R-ADM-0419 / S2R-RUN-0419 | Services fail to start. | The S2R_CREDENTIAL_KEY environment variable is unset or blank. Set a valid 32-byte base64 key and redeploy the application. |
S2R-ADM-0421 | Credential creation or update operations fail. | The pgcrypto extension is not enabled in the PostgreSQL database. A privileged database user must run CREATE EXTENSION pgcrypto; on the target database. |
S2R-RUN-0413 | Requests fail with HTTP 413. | The request payload exceeds the 30 MB size limit. |
S2R-ADM-0424 / S2R-RUN-0415 | Import fails or runtime calls fail. | The service uses the unsupported RPC/encoded SOAP style. This style is out of scope for v1.0. |
To confirm which version of the code is running, check the boot logs for the service. Each service records its deployment provenance at startup, including the commit, branch, timestamp, and image tag.