Runtime (data-plane) API

The Runtime API is the live conversion traffic surface of SOAP-2-REST by Specaria. It is the only API your API consumers and SOAP clients ever touch directly. The platform matches an inbound request to a published route, converts the payload, calls the backend, converts the response, and returns it — all keyed by a correlation ID.

• Base path pattern: /{direction}/{environment}/{serviceKey}/{operationPath...}
• Directions: publish (REST → SOAP) and consume (SOAP → REST)
• Auth: the inbound caller is authenticated by your ingress/gateway in front of the runtime; the runtime is internal-only and never published directly. The runtime's own credential handling concerns the backend call it makes — see backend credential encryption.
• Errors: the standard error envelope on /publish/...; a SOAP Fault envelope on /consume/....

For the canonical, field-level definition see docs/lld/runtime-api.md in the product repository.

---

The direction segment is mandatory

Every conversion route begins with a direction segment. The stored route path is direction-agnostic (/{environment}/{serviceKey}/{operationKey}); the runtime strips the leading /{direction}/ before matching and carries the direction separately. Operator-facing URLs — this reference, the Services Inventory URL button, the OpenAPI servers[0].url, and the Consume WSDL link — always include the prefix.

Examples:

POST /publish/dev/vehicle/license-status        # Publish — SOAP backend exposed as REST
POST /publish/prod/mot/data-sent-to-office-request
POST /consume/prod/legacy-citizen/get-citizen   # Consume — REST backend exposed as SOAP
GET  /publish/dev/citizen/{citizenId}           # placeholder template route

A request that omits or misspells the direction segment (for example /{env}/{serviceKey}) is rejected with 400 S2R-RUN-0405. The error includes a suggestedPath that prepends /publish/, and the Observability page surfaces a Bad-URL Attempts tile counting these hits per attempted path. Zero attempts is the expected steady state for correctly wired clients.

A request that includes a valid direction but matches no published route returns 404 S2R-RUN-0404.

---

PUBLISH direction — REST in, SOAP out

POST /publish/{env}/{serviceKey}/{op...} exposes a SOAP backend as a REST/JSON API.

• Inbound Content-Type: application/json (primary). application/xml is accepted on a per-operation basis as a SOAP-fragment passthrough.
• Generated GET/DELETE routes accept path-placeholder and query-string parameters; these are merged into the effective JSON payload before SOAP conversion.
• The runtime builds the SOAP envelope from the active request mapping, calls the backend with the configured timeout/retry policy, then maps the SOAP response body (or fault) back to a REST payload (or error).

Success response

The response carries X-Correlation-Id and Content-Type headers and a normalized body envelope:

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

Errors (PUBLISH)

Errors use the JSON error envelope with an S2R-RUN-* or S2R-VAL-* code, for example S2R-VAL-0400 (request validation), S2R-RUN-0424 (timeout), S2R-RUN-0429 (retries exhausted), S2R-RUN-0502 (SOAP fault), or S2R-RUN-0506 (backend response contract drift). See error codes.

---

CONSUME direction — SOAP in, REST out

POST /consume/{env}/{serviceKey}/{op...} exposes a migrated REST backend as a SOAP service, so existing SOAP clients keep working unchanged.

• Method: POST only. Any other method on a /consume/... path returns 405 S2R-RUN-0411.

• Inbound Content-Type: both SOAP versions are accepted —

  • SOAP 1.1 → text/xml
  • SOAP 1.2 → application/soap+xml

  The runtime detects the version from the envelope namespace and builds the response in the matching version. An unsupported content type returns 400 S2R-RUN-0408; a malformed envelope returns 400 S2R-RUN-0409 (as a soap:Client fault).

• The runtime maps the inbound SOAP body to a REST/JSON request, calls the REST backend with outbound auth (none, basic, bearer, OAuth2 client-credentials, API-key header, or mutual TLS), and assembles the JSON response back into a SOAP envelope.

• CONSUME routes honor the backend profile's retry_count / retry_backoff_ms with capped exponential backoff.

Errors (CONSUME)

All errors on the CONSUME path are returned as a SOAP Fault envelope (with Content-Type: application/soap+xml or text/xml), because a SOAP client requires a fault response rather than a JSON body. The same S2R-* error codes apply — for example a backend 4xx surfaces as S2R-RUN-0410 (soap:Client), a backend auth-config gap as S2R-RUN-0505, and a serialization/envelope-build failure as S2R-RUN-0506. An oversized payload on a CONSUME route returns a SOAP Fault (soap:Client, HTTP 413) rather than the JSON form.

WSDL serve-back

A CONSUME service publishes a WSDL as its consumer-facing contract, served directly off the runtime:

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

Both forms return the active version's WSDL with Content-Type: application/wsdl+xml; charset=UTF-8. A stored WSDL that cannot be parsed returns 500 S2R-RUN-0421.

---

Request headers

| Header | Direction | Notes | |---|---|---| | Content-Type | both | application/json (PUBLISH primary); text/xml / application/soap+xml (CONSUME). | | Accept | PUBLISH | Defaults to application/json. | | X-Correlation-Id | both | Optional; the runtime generates one when absent and echoes it on the response. | | X-Debug-Enabled | both | Optional; honored only for authorized internal callers/policies. |

Query-string parameters are supported on generated GET/DELETE routes and merged into the effective payload before conversion. Payload handling is UTF-8 end to end, including Hebrew text across REST JSON, generated SOAP XML, backend responses, and saved traces.

---

Payload size limit

The synchronous payload ceiling is 30 MB. A request that exceeds it returns:

• HTTP 413, error code S2R-RUN-0413, with maxPayloadMb=30 in the error details.
• On PUBLISH, the JSON error envelope.
• On CONSUME, a SOAP Fault envelope (soap:Client, HTTP 413, Content-Type: application/soap+xml).

---

Timeouts, retries & resilience

• Default timeout: 1000 ms. Default retries: 2. Both are overridable per operation from the control plane.
• Fault mapping — SOAP faults map to deterministic HTTP statuses (client → 400, server → 502, timeout → 504, connection/IO failure → 503), overridable per operation via a fault mapping table.
• Circuit breaker — process-local per backend endpoint: opens after 5 consecutive transport failures, stays open 30s, then allows a single half-open probe. While open, the runtime returns 503 S2R-RUN-0529. Tunable via S2R_RUNTIME_CB_FAILURE_THRESHOLD and S2R_RUNTIME_CB_OPEN_SECONDS.
• Fallback policy — an operation may configure a transport-failure fallback (timeout / io_error / unknown_error / circuit_open) that returns a configured payload/status. When applied, the response carries X-S2R-Fallback: true and the runtime log result_code is fallback.

---

SOAP version & backend auth

The runtime reads the backend soap_version and emits the matching envelope namespace and content type:

• SOAP 1.1 → http://schemas.xmlsoap.org/soap/envelope/, text/xml; charset=utf-8, optional SOAPAction header.
• SOAP 1.2 → http://www.w3.org/2003/05/soap-envelope, application/soap+xml; charset=utf-8, with an action="…" media-type parameter when a SOAP action exists.

Backend auth modes: none, basic, bearer, api_key_header, and oauth2_client_credentials; mutual TLS (mtls_enabled=true) is orthogonal to the auth type and applies to both the backend call and the OAuth2 token-endpoint call. Credential material is decrypted on demand from the backend profile. A missing credential key at startup raises S2R-RUN-0419 and the runtime refuses traffic; a missing/unparseable mTLS certificate raises S2R-RUN-0420. See backend credential encryption.

---

Related pages

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

---

All Specaria SOAP to REST docs