Loading…
Loading…
The Admin API is the control plane for SOAP-2-REST by Specaria. Everything the no-code UI does — importing WSDLs, creating services and operations, configuring…
The Admin API is the control plane for SOAP-2-REST by Specaria. Everything the no-code UI does
— importing WSDLs, creating services and operations, configuring backends, editing and
versioning mappings, generating OpenAPI, managing settings and roles, and querying every
observability surface — runs against /admin/v1/*.
This page groups the surface by capability and documents representative endpoints. It is not
an exhaustive contract dump; for the canonical, field-level definition see the low-level design
at docs/lld/control-plane-api.md in the product repository.
/admin/v1S2R-ADM-* (or S2R-VAL-*) code.GET /admin/v1/me returns the resolved caller identity and application role.
WSDL is the entry point for a Publish-direction service. The import endpoints validate, parse, and persist the WSDL artifact and its operation catalog, and return a rich onboarding preview (backend suggestion, zero-touch readiness summary, per-operation sample payloads, and a diff against any prior comparable import).
| Method & path | What it does |
|---|---|
| POST /admin/v1/wsdl/import | Upload a WSDL file (multipart/form-data, file field). |
| POST /admin/v1/wsdl/import-url | Fetch a WSDL from a URL. |
| POST /admin/v1/wsdl/import-xml | Import pasted/repaired WSDL XML directly. |
| POST /admin/v1/wsdl/namespace-repair-preview | Preview namespace declarations the parser will auto-repair. |
| POST /admin/v1/wsdl/external-reference-preview | Check external WSDL/XSD reference health before import. |
| POST /admin/v1/wsdl/repair-report · :repair-package | Combined repair diagnostics; the package form returns a ZIP with the repaired root WSDL and resolvable references. |
| GET /admin/v1/wsdl/import/{artifactId} | Retrieve a persisted import artifact and its parsed operations. |
| POST /admin/v1/wsdl/import/{artifactId}/generate-service | Generate a draft service + version + operations from an imported catalog. |
The :autopilot variants import a WSDL and generate the first draft (service, operations,
inferred backend, and mappings) in a single call, returning an artifact preview, draft
suggestion, generated objects, and a publish-readiness assessment:
POST /admin/v1/wsdl/import:autopilot (file)POST /admin/v1/wsdl/import-url:autopilot (URL)POST /admin/v1/wsdl/import-xml:autopilot (pasted XML)POST /admin/v1/wsdl/import/{artifactId}:autopilot (already-imported artifact)POST /admin/v1/wsdl/import-urls:autopilot · :import-files:autopilot — batch import many
WSDLs at once, with a per-item result/summary.See Zero-touch autopilot.
| Method & path | What it does |
|---|---|
| POST /admin/v1/services | Create a logical service (serviceKey, serviceName, environment). |
| GET /admin/v1/services | List services, paged, with q / environment / traffic filters. |
| GET /admin/v1/services/{serviceId} | Get one service. |
| PATCH /admin/v1/services/{serviceId} | Update metadata, status (active/disabled), and debugEnabled. |
| POST /admin/v1/services:bulk-action | Inventory-first bulk enable / disable / debug_on / debug_off / delete. |
| DELETE /admin/v1/services/{serviceId} | Soft-delete (sets status=deprecated). |
| DELETE /admin/v1/services/{serviceId}:hard-delete | Permanent delete of the service and its dependent objects (admin only; rejected with 409 S2R-ADM-0410 while the service is active). |
Operation and mapping edits are allowed only while the parent service version is a draft
and not active; attempting them on an active/immutable version returns 409 with
S2R-ADM-0410.
| Method & path | What it does |
|---|---|
| GET /admin/v1/services/{serviceId}/versions/{versionId}/operations | List generated operations. |
| PATCH /admin/v1/operations/{operationId} | Edit restMethod / restPath / timeoutMs / retryCount. |
| GET · PATCH /admin/v1/operations/{operationId}/validation-rules | Read / override per-field request/response validation (regex-focused override flow). |
| GET · PUT /admin/v1/operations/{operationId}/transform-rules | Read / replace no-code transform rules (trim, uppercase, lowercase, default_value, rename, split, join, date_format). |
| GET · PUT /admin/v1/operations/{operationId}/mapping | Read / replace the active request/response/fault mapping (manual override). |
| GET /admin/v1/operations/{operationId}/mapping-diagnostics | Readiness for one operation (AUTO_READY / AUTO_READY_WITH_WARNINGS / MANUAL_REQUIRED). |
| GET /admin/v1/services/{serviceId}/mapping-diagnostics | Per-operation diagnostics for the whole service, with summary counters. |
| POST /admin/v1/operations/{operationId}/mapping:regenerate | Regenerate auto mapping from the stored contract (preserves fault mapping). |
| POST /admin/v1/services/{serviceId}/mapping:regenerate | Regenerate mappings across all draft operations. |
A PUT to the mapping endpoint deactivates the previous active mapping and creates a new
mapping version (mappingVersion increments). See How mapping works
and Field-level overrides.
A backend profile holds the SOAP endpoint URL, auth mode, transport timing, and encrypted
credentials for a service. Credentials are never echoed back — responses return only a
metadata envelope ({ "set": true, "lastUpdatedAt": …, "lastUpdatedBy": … }).
| Method & path | What it does |
|---|---|
| GET · POST /admin/v1/services/{serviceId}/backend-profiles | List / create profiles. |
| PATCH /admin/v1/backend-profiles/{profileId} | Update endpoint / auth / timeout / retry. |
| DELETE /admin/v1/backend-profiles/{profileId} | Delete a profile (default is reassigned if needed). |
| POST /admin/v1/backend-profiles/{profileId}:test-connection | DNS / TCP / WSDL-pull diagnostics. |
| POST /admin/v1/backend-profiles/{profileId}:test-application | Run a real backend SOAP test for one operation and save preview payloads. |
| POST /admin/v1/backend-profiles/{profileId}:test-generated-samples | Auto-generate request payloads from the contract and run application tests (single op or batch smoke test). |
| POST /admin/v1/backend-profiles/{profileId}:test-rest | REST-style (Postman-like) test. |
| GET /admin/v1/backend-profiles/{profileId}/test-previews | Recent saved test previews for the profile. |
Supported authType values: none, basic, bearer, api_key_header,
oauth2_client_credentials; mTLS (mtlsEnabled=true) is orthogonal to the auth type. All
credential material is stored encrypted at rest (pgcrypto under an app-held key). See
backend credential encryption.
Supporting onboarding endpoints also live here: synthetic-monitor configuration
(GET/POST /admin/v1/services/{serviceId}/synthetic-monitor) and reusable named test
datasets (GET/POST /admin/v1/services/{serviceId}/test-datasets,
DELETE /admin/v1/test-datasets/{datasetId}).
Mappings are versioned and immutable. A draft version is cloned, edited, validated against publish-readiness, then activated; activation can be rolled back.
| Method & path | What it does |
|---|---|
| GET /admin/v1/services/{serviceId}/versions | List versions (newest first). |
| POST /admin/v1/services/{serviceId}/versions | Create a new draft by cloning operations + active mappings (409 S2R-ADM-0410 if a draft already exists). |
| GET /admin/v1/services/{serviceId}/versions/{versionId}/publish-readiness | Readiness assessment (READY_TO_PUBLISH / READY_WITH_RISK / BLOCKED) with checks, blocking issues, and suggested actions. |
| POST /admin/v1/services/{serviceId}/versions/{versionId}:activate | Activate a draft (guarded by readiness; a BLOCKED draft returns 409 S2R-ADM-0410). |
| POST /admin/v1/services/{serviceId}/versions/{versionId}:rollback | Roll back to a selected version. |
| GET /admin/v1/services/{serviceId}/versions/{versionId}/wsdl-drift | Drift assessment against the newest comparable import (UP_TO_DATE / DRIFT_DETECTED / BREAKING_DRIFT / UNTRACKED). |
| POST /admin/v1/services/{serviceId}/versions/{versionId}:generate-replacement-draft | Create a fresh draft from a newer WSDL import, preserving REST route/timeout/retry settings where the operation still exists. |
See Publish & version a service.
| Method & path | What it does |
|---|---|
| POST /admin/v1/services/{serviceId}/versions/{versionId}:generate-openapi | Generate an OpenAPI v3 artifact (admin only). |
| GET /admin/v1/services/{serviceId}/versions/{versionId}/openapi | Download the generated OpenAPI v3 JSON (X-OpenAPI-SHA256 header). |
| GET /admin/v1/services/{serviceId}/versions/{versionId}/openapi/package | Download a versioned ZIP (openapi.json, mapping-metadata.json, checksums.json). |
See Generate & review the OpenAPI.
| Method & path | What it does |
|---|---|
| GET · PATCH /admin/v1/settings | Read / update mutable settings: default_timeout_ms, default_retry_count, default_retention_days, debug toggles, and SMTP alert delivery settings. |
| GET /admin/v1/settings/alert-mail-history | Recent SMTP alert delivery history. |
| GET · PUT /admin/v1/role-bindings | Read / replace IdP-group → app-role bindings. |
| GET /admin/v1/permission-bindings · POST · DELETE /admin/v1/permission-bindings/{bindingId} | Manage direct in-app user → role assignments (the durable fallback when group lookup is unavailable). |
Every settings or role change emits an audit event. See RBAC & roles and Audit trail.
All of these read from pre-computed aggregation tables rather than raw logs at query time (except correlation-ID drill-down). See Observability overview.
| Method & path | What it does |
|---|---|
| GET /admin/v1/metrics | Aggregated metrics by window (15m/1h/24h/7d/30d/60d) with request/error counts and p50/p95/p99 latency plus converter overhead. |
| GET /admin/v1/slo-report | SLO status with availability/latency targets, breach detection, and a timeline. |
| GET /admin/v1/service-metric-timeline | Per-service request/error trend over time. |
| GET /admin/v1/runtime-logs | Search runtime logs by environment, service, operation, correlationId, resultCode, window (paged). |
| GET /admin/v1/backend-test-previews | Search saved backend test previews. |
| GET /admin/v1/async-executions | Search async callback executions; plus {id}/replay-preview, {id}/reprocess, callback preview/reprocess, and manual complete/fail. |
| GET /admin/v1/observability-filter-options | Filter dropdown option lists for the UI. |
| GET /admin/v1/debug-traces/{correlationId} · /replay-metadata | Debug trace payloads and replay metadata for a correlation ID. |
| GET /admin/v1/audit-events | Query audit history (paged, windowed). |
→ Metrics & SLO reports · Logs & tracing · Audit trail
Backend test endpoints (:test-application, :test-generated-samples, :test-rest) let an
operator run a real or generated request against a backend and inspect the SOAP request, SOAP
response, and converted REST preview — UTF-8 and Hebrew text are preserved across the whole
chain. Previews can optionally be saved and are then visible in
Observability. The product also offers a JWT-gated
runtime test surface used by the onboarding wizard; it is internal to the platform's own UI
flow and gated by an operator-provisioned signing key.