Loading…
Loading…
SOAP-2-REST by Specaria exposes three distinct API surfaces. They serve different audiences, sit behind different access controls, and use different…
SOAP-2-REST by Specaria exposes three distinct API surfaces. They serve different audiences, sit behind different access controls, and use different conventions. Knowing which one you are talking to is the first step:
| Surface | Base path | Audience | Purpose |
|---|---|---|---|
| Control-plane (Admin) API | /admin/v1/* | Operators & platform teams | No-code management of the platform: WSDL import, services, mappings, backends, settings, roles, and all observability queries. |
| Runtime (Data-plane) API | /{direction}/{env}/... | API consumers / SOAP clients | The live conversion traffic surface. Publish exposes a SOAP backend as REST; Consume exposes a REST backend as SOAP. |
| Ingest API | /ingest/v1/* | Edge connectors (internal) | Receives traffic-log feeds from gateway/load-balancer connectors (for example the F5 relay) that power traffic-driven discovery. Not a customer-called API. |
The two surfaces you integrate against are the Admin API and the Runtime API. The Ingest API is an internal plumbing surface used by the platform's own connectors and is documented in the discovery section rather than here.
The Admin API is not publicly reachable. In a standard deployment it sits behind an
identity-aware ingress (Google IAP, or an OIDC/SAML front door), and every /admin/v1/*
endpoint enforces role-based authorization.
The platform resolves the caller's identity from forwarded identity headers:
X-Goog-Authenticated-User-EmailX-Goog-Authenticated-User-Groups (comma-separated group emails)The resolved identity maps to one of three application roles — admin, operator,
reader — through role bindings. Bindings can come from IdP group membership, from direct
in-app principal assignments, or from an emergency bootstrap list. See
RBAC & roles for the resolution order and what each role may do. A
forbidden call returns S2R-ADM-0403.
GET /admin/v1/me returns the resolved identity and role, which the UI uses for its header
and context display.
The runtime conversion surface is the traffic path itself. Authentication of the inbound caller is handled 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 downstream — see backend credential encryption and the runtime API page.
/admin/v1. Paths in this reference are written
relative to that base (for example GET /admin/v1/services)./publish/{env}/{serviceKey}/{op...} or /consume/{env}/{serviceKey}/{op...}. A request
that omits the direction segment is rejected with S2R-RUN-0405.Every runtime request is tagged with a correlation ID that travels through the whole request lifecycle — inbound REST/SOAP call, backend SOAP/REST call, mapping, structured log, and any debug trace.
X-Correlation-Id on a runtime request to supply your own; the runtime generates one
when the header is absent.X-Correlation-Id) and is the join key
across every observability surface: searchable logs, live traffic, debug traces, and async
callback tracking.Both API surfaces return errors in a single, consistent JSON shape:
{
"error": {
"code": "S2R-RUN-0413",
"message": "Payload too large",
"details": {
"maxPayloadMb": 30
},
"correlationId": "00000000-0000-0000-0000-000000000000"
}
}
code — a stable S2R-<AREA>-<NNNN> error code. See error codes.message — a human-readable summary, safe to surface in logs and UIs.details — a code-specific object with extra context (it may be empty {}).correlationId — the request's correlation ID, for cross-referencing in observability.CONSUME exception. On the SOAP-facade (
/consume/...) path, errors are returned as a SOAP Fault envelope (withContent-Type: application/soap+xmlortext/xml) rather than this JSON shape, because SOAP clients require a fault response. The same error codes apply; see the runtime API page.