Runtime API Reference

Overview

The Runtime API is the live data plane for all conversion traffic. It is the endpoint that API consumers interact with, typically through an API gateway or ingress controller. The Runtime API itself is designed for internal network access and should not be exposed directly to the public internet.

Its core function is to receive an inbound request, match it to a configured service operation, and perform a protocol and payload transformation. This process is bidirectional, supporting two primary conversion flows identified by a mandatory direction segment in the request path:

• publish: Exposes a SOAP backend as a modern REST/JSON API. API consumers make REST requests, and the runtime converts them into SOAP requests for the backend.
• consume: Exposes a REST backend as a traditional SOAP web service. This allows legacy SOAP clients to interact with new or migrated REST services without modification.

Every request processed by the runtime is assigned a unique correlation ID, which is returned in the X-Correlation-Id response header to facilitate tracing and debugging.

How It Works

The runtime's behavior is determined by the direction segment of the incoming request URL. It routes traffic, performs transformations, and interacts with backend services based on this direction.

Request Flow

All requests to the runtime follow the path pattern /{direction}/{environment}/{serviceKey}/{operationPath...}. The runtime first inspects the {direction} segment to determine the conversion flow (publish or consume). It then strips this segment and uses the remaining path (/{environment}/{serviceKey}/{operationPath...}) to match the request against a stored route configuration.

The following diagram illustrates the two conversion flows:

flowchart TD
    subgraph "API Consumer"
        direction LR
        A[REST Client]
        B[SOAP Client]
    end

    subgraph "API Gateway / Ingress"
        C(Gateway)
    end

    subgraph "Runtime API"
        D{Request Router<br>/direction/...}
        D -- /publish --> E[REST-to-SOAP Conversion]
        D -- /consume --> F[SOAP-to-REST Conversion]
    end

    subgraph "Backend Services"
        G[SOAP Backend]
        H[REST Backend]
    end

    A -- REST Request --> C
    B -- SOAP Request --> C
    C --> D

    E -- SOAP Request --> G
    G -- SOAP Response --> E
    E -- REST Response --> C

    F -- REST Request --> H
    H -- REST Response --> F
    F -- SOAP Response --> C

    C -- REST Response --> A
    C -- SOAP Response --> B

Publish Flow: REST to SOAP

When the direction is publish, the runtime exposes a SOAP backend as a REST API.

1. An API consumer sends a REST request (e.g., POST, GET, DELETE) to a /publish/... endpoint. The primary inbound content type is application/json.
2. For GET or DELETE requests, any path placeholders and query string parameters are merged into a single effective JSON payload.
3. The runtime uses the active request mapping for the matched operation to transform the JSON payload into a SOAP envelope.
4. It sends the SOAP request to the configured backend, respecting any specified timeout and retry policies.
5. Upon receiving the response, the runtime maps the SOAP response body back to a JSON result object. If the backend returns a SOAP Fault, it is mapped to a standard JSON error envelope.
6. The final JSON response is returned to the API consumer.

Consume Flow: SOAP to REST

When the direction is consume, the runtime exposes a REST backend as a SOAP web service, ensuring continuity for legacy clients.

1. A SOAP client sends a POST request containing a SOAP envelope to a /consume/... endpoint.
2. The runtime accepts both SOAP 1.1 (text/xml) and SOAP 1.2 (application/soap+xml) and automatically detects the version from the envelope's namespace.
3. The runtime extracts the SOAP body and maps it to a JSON payload.
4. It calls the configured REST backend, applying any specified outbound authentication (e.g., Bearer token, API Key, mTLS).
5. The JSON response from the REST backend is assembled back into a SOAP envelope that matches the version of the original request.
6. The SOAP response (or a SOAP Fault in case of an error) is returned to the client.

API Endpoints

The Runtime API uses a structured path to identify the service, operation, and conversion direction.

Endpoint Path Structure

The base path for all runtime operations follows this pattern:

/{direction}/{environment}/{serviceKey}/{operationPath...}

• direction: Must be either publish or consume. A request with a missing or incorrect direction will be rejected with HTTP 400 and error code S2R-RUN-0405.
• environment: The deployment environment (e.g., dev, prod).
• serviceKey: The unique identifier for the service.
• operationPath: The path identifying the specific operation within the service.

Examples:

# Publish direction: Exposing a SOAP backend as REST
POST /publish/dev/vehicle/license-status
GET  /publish/dev/citizen/{citizenId}

# Consume direction: Exposing a REST backend as SOAP
POST /consume/prod/legacy-citizen/get-citizen

PUBLISH Direction (/publish/...)

Exposes a SOAP backend as a REST API.

• Methods: POST, GET, DELETE.
• Inbound Content-Type: application/json. Per-operation, application/xml can be accepted for SOAP-fragment passthrough.
• Parameters: For GET and DELETE requests, path and query string parameters are supported and are merged into the JSON payload before conversion.

Success Response

A successful publish request returns a 200 OK with a standard JSON envelope containing metadata and the result.

{
  "correlationId": "...",
  "environment": "prod",
  "path": "/publish/prod/vehicle/license-status",
  "serviceKey": "vehicle",
  "operationKey": "license-status",
  "backendLatencyMs": 38,
  "result": { "...": "mapped SOAP payload" }
}

Error Response

Errors on the publish path are returned in a standard JSON error envelope. See the Troubleshooting section for common error codes.

CONSUME Direction (/consume/...)

Exposes a REST backend as a SOAP API.

• Method: POST only. Using any other HTTP method on a /consume path will result in an HTTP 405 error (S2R-RUN-0411).
• Inbound Content-Type:
  • text/xml for SOAP 1.1
  • application/soap+xml for SOAP 1.2

Error Response

All errors on the consume path, including validation failures and backend errors, are returned as a SOAP Fault envelope. This ensures that the SOAP client receives an error in the format it expects. The fault will contain the relevant S2R-* error code.

WSDL Endpoint

For each consume service, the runtime serves a dynamically generated Web Services Description Language (WSDL) file. This file acts as the formal contract for SOAP clients.

• Endpoints:
  • GET /consume/{env}/{serviceKey}?wsdl
  • GET /consume/{env}/{serviceKey}/wsdl
• Response: Both endpoints return the WSDL for the service's active version with a Content-Type of application/wsdl+xml; charset=UTF-8.
• Error: If the stored WSDL for the service cannot be parsed, the endpoint returns an HTTP 500 error with code S2R-RUN-0421.

Resilience and Fault Tolerance

The runtime includes several features to ensure resilience when communicating with backend services.

Timeouts and Retries

The runtime applies timeout and retry policies to backend calls, which can be configured on a per-operation basis.

• Default Timeout: 1000 ms
• Default Retries: 2

In the consume direction, retries use a capped exponential backoff strategy, configured via retry_count and retry_backoff_ms in the backend profile.

Circuit Breaker

The runtime implements a process-local circuit breaker for each backend endpoint to prevent repeated calls to a failing service.

• Mechanism: The breaker opens after a configured number of consecutive transport failures. While open, all subsequent requests to that backend fail immediately with a 503 Service Unavailable error (S2R-RUN-0529). After a cooldown period, the breaker enters a "half-open" state, allowing a single probe request to pass through. If it succeeds, the breaker closes; if it fails, the breaker re-opens.
• Configuration: The circuit breaker is tunable via environment variables.

Fallback Policy

Operations can be configured with a fallback policy to handle specific transport failures (timeout, io_error, unknown_error, circuit_open). When a configured failure occurs and a fallback is defined, the runtime returns a pre-configured static payload and status code instead of an error.

When a fallback is triggered, the response will include the header X-S2R-Fallback: true.

Headers and Payloads

Request Headers

The runtime processes the following HTTP headers on inbound requests.

Payload Size Limit

The maximum synchronous payload size is 30 MB.

• A request with a body larger than this limit will be rejected with an HTTP 413 Payload Too Large status and error code S2R-RUN-0413.
• On the publish path, the error is a JSON envelope.
• On the consume path, the error is a soap:Client Fault.

Payload Encoding

The platform handles UTF-8 encoding end-to-end. This includes REST JSON payloads, generated SOAP XML, backend responses, and saved traces.

Backend Integration

SOAP Version Handling

When calling a SOAP backend (publish direction), the runtime uses the soap_version configured in the backend profile to construct the correct envelope.

• SOAP 1.1: Uses the http://schemas.xmlsoap.org/soap/envelope/ namespace and sends Content-Type: text/xml; charset=utf-8. It may also include a SOAPAction header.
• SOAP 1.2: Uses the http://www.w3.org/2003/05/soap-envelope namespace and sends Content-Type: application/soap+xml; charset=utf-8. Any SOAP action is included as a media-type parameter (e.g., action="...").

Backend Authentication

The runtime can authenticate to backends using several methods, configured in the backend profile. Credential material is stored encrypted and decrypted on-demand by the runtime.

• Supported Modes: none, basic, bearer, api_key_header, oauth2_client_credentials.
• Mutual TLS: mtls_enabled=true can be combined with any authentication type. It applies to both the direct backend call and any calls to an OAuth2 token endpoint.

Troubleshooting

The runtime returns specific error codes to help diagnose issues. On the publish path, these are in a JSON error envelope. On the consume path, they are inside a SOAP Fault.

See Also

• API reference overview
• Admin (control-plane) API
• Error codes
• Consume direction (SOAP facade)
• Observability overview
• Backend Credential Encryption

All SOAP-to-REST docs