Runtime API Reference

Overview

The Runtime API is the live data-plane traffic endpoint for the SOAP-2-REST platform. It is the sole API surface that API consumers and legacy SOAP clients interact with directly. The runtime is an internal-only component, designed to be placed behind an API publisher's own ingress or gateway, which handles inbound authentication.

When a request arrives, the runtime performs the following sequence of operations:

1. Matches the inbound request path to a configured route.
2. Converts the request payload between JSON and SOAP, based on the route's direction.
3. Calls the configured backend service, handling authentication to that backend.
4. Converts the backend's response or fault.
5. Returns the final response to the original caller.

All operations are tracked with a correlation ID, which is either provided by the caller or generated by the runtime.

How it works

The core of the Runtime API is a path-based routing system that distinguishes between two fundamental conversion directions: publish (exposing a SOAP backend as REST) and consume (exposing a REST backend as SOAP).

Base Path and Routing

All runtime requests must follow a specific path pattern:

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

• direction: Must be either publish or consume. This segment is mandatory. The runtime strips this segment before matching against the stored route (/{environment}/{serviceKey}/{operationKey}), but uses the direction to control the conversion logic.
• environment: The deployment environment, e.g., dev or prod.
• serviceKey: The unique identifier for the service.
• operationPath...: The path identifying the specific operation within the service.

A request that omits or misspells the direction segment (e.g., /{env}/{serviceKey}) is rejected with an HTTP 400 and error code S2R-RUN-0405. The error response includes a suggestedPath field that prepends /publish/ to the attempted path. A request with a valid direction that does not match any published route receives an HTTP 404 with error code S2R-RUN-0404.

Example Paths:

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

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

publish Direction: REST in, SOAP out

The publish direction exposes a SOAP backend as a modern REST/JSON API.

• Path: POST /publish/{env}/{serviceKey}/{op...}
• Inbound Request: The primary expected Content-Type is application/json. application/xml is also accepted on a per-operation basis for SOAP-fragment passthrough. For GET or DELETE methods, path placeholders and query-string parameters are merged into an effective JSON payload before conversion.
• Processing Flow: The runtime receives the REST request, builds a complete SOAP envelope using the active request mapping, and calls the backend SOAP service. It then maps the SOAP response body or fault back into a REST payload or a standard JSON error envelope.
• Success Response: A successful response includes X-Correlation-Id and Content-Type headers, along with a normalized JSON body.

Example publish Success Response:

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

consume Direction: SOAP in, REST out

The consume direction provides a SOAP facade for a REST backend, allowing legacy SOAP clients to work with migrated services without modification.

• Path & Method: POST /consume/{env}/{serviceKey}/{op...}. This path accepts POST requests only. Any other HTTP method will result in a 405 Method Not Allowed response with error code S2R-RUN-0411.
• Inbound Request: The runtime accepts both major SOAP versions, identified by Content-Type:
  • SOAP 1.1: text/xml
  • SOAP 1.2: application/soap+xml The runtime automatically detects the SOAP version from the envelope namespace and formats the response in the same version.
• Processing Flow: The runtime maps the inbound SOAP body to a REST/JSON request, calls the backend REST service using the configured authentication method (e.g., Basic, Bearer, OAuth2, API Key), and assembles the JSON response back into a SOAP envelope.
• WSDL Generation: A consume service makes its contract available as a WSDL document. The WSDL can be retrieved via a GET request to either of the following paths:
  • GET /consume/{env}/{serviceKey}?wsdl
  • GET /consume/{env}/{serviceKey}/wsdl The response will have a Content-Type of application/wsdl+xml; charset=UTF-8.

Request Headers

Header	Direction	Notes
Content-Type	Both	application/json (primary for publish); text/xml or application/soap+xml for consume.
Accept	publish	Defaults to application/json.
X-Correlation-Id	Both	Optional on request. The runtime generates one if absent and always includes it on the response.
X-Debug-Enabled	Both	Optional. Honored only for authorized internal callers or policies.

Payload Handling

• Character Encoding: The platform uses UTF-8 encoding end-to-end.
• Size Limit: The maximum synchronous payload size is 30 MB. A request exceeding this limit is rejected with an HTTP 413 Payload Too Large status and error code S2R-RUN-0413. The error details include maxPayloadMb=30. The error format is a JSON envelope for publish routes and a SOAP Fault for consume routes.

Resilience and Backend Integration

The runtime includes several features for resilient integration with backend services.

Timeouts and Retries

• Default Timeout: 1000 ms
• Default Retries: 2

Both settings can be overridden on a per-operation basis from the control plane. For consume routes, retries use a capped exponential backoff strategy.

Circuit Breaker

The runtime implements a process-local circuit breaker for each backend endpoint to prevent cascading failures.

• The breaker opens after 5 consecutive transport failures.
• It remains open for 30 seconds, during which requests fail fast with 503 Service Unavailable and error code S2R-RUN-0529.
• After 30 seconds, it enters a half-open state, allowing a single probe request to pass through. A successful probe closes the circuit; a failure keeps it open.

These values are tunable via the following environment variables:

• S2R_RUNTIME_CB_FAILURE_THRESHOLD
• S2R_RUNTIME_CB_OPEN_SECONDS

Fallback Policy

Operations can be configured with a fallback policy for transport failures (timeout, io_error, unknown_error, circuit_open). If a fallback is triggered, the runtime returns a pre-configured payload and status code. The response will include the header X-S2R-Fallback: true.

Backend Authentication and SOAP Version

The runtime manages credentials and protocol details for backend calls.

• Authentication: Supported modes for backend calls include none, basic, bearer, api_key_header, and oauth2_client_credentials. Mutual TLS (mtls_enabled=true) can be applied to any backend call, including the token endpoint call for OAuth2. Credentials are encrypted and decrypted on demand.
• SOAP Version: The runtime emits the correct SOAP envelope namespace and Content-Type based on the backend's configured soap_version.
  • SOAP 1.1: http://schemas.xmlsoap.org/soap/envelope/, text/xml; charset=utf-8. May include a SOAPAction header.
  • SOAP 1.2: http://www.w3.org/2003/05/soap-envelope, application/soap+xml; charset=utf-8. May include an action parameter in the media type.

Troubleshooting

Error responses from the Runtime API depend on the direction of the request.

• publish direction: Errors are returned in a standard JSON error envelope with an S2R-* error code.
• consume direction: All errors are returned as a SOAP Fault envelope to satisfy the expectations of a SOAP client. The fault will contain the relevant S2R-* error code.

Error Code	HTTP Status	Trigger Condition
S2R-RUN-0404	404	A validly formed request path that does not match any published route.
S2R-RUN-0405	400	The direction segment (/publish/ or /consume/) is missing or misspelled.
S2R-RUN-0408	400	An unsupported Content-Type was sent to a /consume endpoint.
S2R-RUN-0409	400	The SOAP envelope on a /consume request is malformed.
S2R-RUN-0410	(Varies)	The REST backend for a /consume route returned a 4xx client error.
S2R-RUN-0411	405	A non-POST method was used on a /consume path.
S2R-RUN-0413	413	Request payload exceeds the 30 MB limit.
S2R-RUN-0419	(Startup)	A required credential key is missing at runtime startup.
S2R-RUN-0420	(Startup)	A required mTLS certificate is missing or unparseable at startup.
S2R-RUN-0421	500	The stored WSDL for a /consume service could not be parsed.
S2R-RUN-0424	(Varies)	Backend call timed out.
S2R-RUN-0429	(Varies)	Backend call failed after all retries were exhausted.
S2R-RUN-0502	502	The SOAP backend returned a SOAP fault.
S2R-RUN-0505	(Varies)	Backend authentication configuration is missing or invalid.
S2R-RUN-0506	(Varies)	Backend response does not match the expected contract (drift).
S2R-RUN-0529	503	The circuit breaker for the backend is open.
S2R-VAL-0400	400	General request validation failure.

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