Runtime (Data Plane) API

Overview

The Runtime API is the live traffic-handling component of the platform. It is the endpoint that API consumers interact with directly to perform SOAP-to-REST and REST-to-SOAP conversions. The runtime's primary function is to receive an inbound request, match it to a configured service route, transform the payload, invoke the backend service, transform the response, and return the result to the original caller.

Each request is assigned a correlation ID, which is used for end-to-end tracing. The Runtime API itself is designed to be an internal service, fronted by an API gateway or ingress controller that manages inbound client authentication. The runtime's own credential management pertains to the outbound calls it makes to backend services.

The API is organized into two primary "directions":

• publish: Exposes a SOAP backend as a modern REST/JSON API.
• consume: Exposes a REST backend as a SOAP web service to support legacy clients.

How It Works

The runtime processes requests based on a URL structure that dictates the conversion direction and identifies the target service and operation.

The base path for all runtime requests follows this pattern: /{direction}/{environment}/{serviceKey}/{operationPath...}

The runtime strips the leading /{direction}/ segment to match the request against a stored route (/{environment}/{serviceKey}/{operationKey}) and processes the request according to that direction.

flowchart TD
    subgraph REST to SOAP (Publish)
        A[API Consumer] -- JSON Request --> B(Runtime API: /publish/...);
        B -- SOAP Request --> C[SOAP Backend];
        C -- SOAP Response --> B;
        B -- JSON Response --> A;
    end

    subgraph SOAP to REST (Consume)
        D[SOAP Client] -- SOAP Request --> E(Runtime API: /consume/...);
        E -- JSON Request --> F[REST Backend];
        F -- JSON Response --> E;
        E -- SOAP Response --> D;
    end

A request that omits or misspells the direction segment will be rejected. If the direction is valid but no matching route is found, the runtime returns a 404 Not Found error.

Example Paths

# Publish direction: Exposes a SOAP backend as a REST API
POST /publish/dev/vehicle/license-status
POST /publish/prod/<customer>/data-sent-to-office-request
GET  /publish/dev/citizen/{citizenId}

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

Publish Direction: REST to SOAP

The publish direction exposes a SOAP backend as a REST/JSON API. The runtime converts an inbound REST request into a SOAP envelope, calls the backend, and transforms the SOAP response back into a JSON payload.

Path: /{publish}/{environment}/{serviceKey}/{operationPath...}

• Inbound Content-Type: The primary expected content type is application/json. application/xml is also accepted for specific operations configured for SOAP-fragment passthrough.
• HTTP Methods: POST is used for standard operations. GET and DELETE routes can be generated, with path and query parameters being merged into a JSON payload before the SOAP conversion.

Success Response

A successful publish request returns a JSON object containing metadata about the transaction and the mapped result from the backend. The response includes X-Correlation-Id and Content-Type: application/json headers.

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

Error Handling

Errors in the publish direction are returned in a standard JSON error envelope. See the Troubleshooting section for specific error codes.

Consume Direction: SOAP to REST

The consume direction exposes a REST backend as a traditional SOAP web service. This allows existing SOAP clients to continue functioning without modification while the backend is migrated to a RESTful architecture.

Path: POST /consume/{environment}/{serviceKey}/{operationPath...}

• Method: Only POST is permitted. Any other HTTP method will result in a 405 Method Not Allowed error (S2R-RUN-0411).
• Inbound Content-Type: The runtime accepts both major SOAP versions, identified by their content type:
  • SOAP 1.1: text/xml
  • SOAP 1.2: application/soap+xml

The runtime detects the SOAP version from the envelope's XML namespace and formats the response (or fault) in the same version.

WSDL Generation

For each consume service, the runtime provides a WSDL document that serves as the contract for SOAP clients. The WSDL can be retrieved via a GET request to one of two endpoints:

• GET /consume/{env}/{serviceKey}?wsdl
• GET /consume/{env}/{serviceKey}/wsdl

Both endpoints return the active WSDL with a Content-Type of application/wsdl+xml; charset=UTF-8.

Error Handling

All errors on consume paths, including validation failures, backend errors, and timeouts, are returned as a SOAP Fault envelope. This ensures that SOAP clients receive an error in the format they expect. The fault will contain the relevant S2R-* error code. For example, an oversized payload results in a soap:Client fault with an HTTP 413 status.

API Reference

Request Headers

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.

• On publish routes, the error is a standard JSON envelope with code S2R-RUN-0413 and maxPayloadMb: 30 in the details.
• On consume routes, the error is a SOAP Fault (soap:Client).

Character Encoding

The runtime handles payloads as UTF-8 end-to-end. This includes JSON requests, generated SOAP XML, backend responses, and stored traces.

Resilience and Fault Tolerance

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

Timeouts and Retries

• Default Timeout: 1000 ms
• Default Retries: 2

Both the timeout and the number of retries can be overridden on a per-operation basis via the control plane. For consume routes, retries use a capped exponential backoff strategy, configurable with 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.

• The breaker opens after 5 consecutive transport failures.
• It remains open for 30 seconds.
• After the open period, it enters a half-open state, allowing a single request to "probe" the backend's health.
• While the circuit is open, requests to that backend fail immediately with error 503 S2R-RUN-0529.

These thresholds are tunable via environment variables.

Fallback Policy

Operations can be configured with a fallback policy for transport failures (timeout, io_error, unknown_error, circuit_open). If a configured failure occurs, the runtime returns a pre-configured static payload and status code instead of an error. When a fallback is triggered, the response includes the header X-S2R-Fallback: true.

Fault Mapping

For publish routes, SOAP faults from the backend are mapped to deterministic HTTP status codes. This mapping is configurable per operation. The default mappings are:

• Client-side SOAP fault → 400 Bad Request
• Server-side SOAP fault → 502 Bad Gateway
• Backend timeout → 504 Gateway Timeout
• Connection/IO failure → 503 Service Unavailable

Backend Integration

SOAP Version Handling

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

• SOAP 1.1:
  • Envelope Namespace: http://schemas.xmlsoap.org/soap/envelope/
  • Content-Type: text/xml; charset=utf-8
  • SOAPAction header is included if specified.
• SOAP 1.2:
  • Envelope Namespace: http://www.w3.org/2003/05/soap-envelope
  • Content-Type: application/soap+xml; charset=utf-8
  • The SOAP action is included as a media-type parameter (e.g., action="...") when present.

Backend Authentication

The runtime supports multiple authentication methods for outbound calls to both SOAP and REST backends. All credential material is decrypted on-demand from the service's backend profile.

• Authentication Types: none, basic, bearer, api_key_header, oauth2_client_credentials.
• Mutual TLS: mTLS can be enabled (mtls_enabled=true) independently of the authentication type. It applies to both the primary backend call and any calls to an OAuth2 token endpoint.

Configuration Reference

The following environment variables can be used to tune the circuit breaker behavior.

Troubleshooting

The runtime returns specific error codes to help diagnose issues.

See Also

• API Reference Overview
• Admin (Control Plane) API
• Error Codes Reference
• Consume Direction (SOAP Facade) Guide
• Observability Overview
• Backend Credential Encryption

All SOAP-to-REST docs