Admin API Reference

Overview

The Admin API provides the administrative control plane for the platform. It is a RESTful API that underpins all configuration and management actions available in the user interface. API publishers use this interface to programmatically manage the entire lifecycle of a SOAP-to-REST service, from initial WSDL import to ongoing monitoring and maintenance.

The Admin API's responsibilities include:

• Importing and parsing WSDL artifacts.
• Creating and managing services, operations, and versions.
• Configuring backend connection profiles and credentials.
• Defining and editing request/response mappings.
• Activating and rolling back service versions.
• Generating OpenAPI specifications.
• Managing platform settings and role-based access control (RBAC).
• Querying observability data, including metrics, logs, and audit events.

All endpoints are located under the base path /admin/v1. Access to every endpoint is controlled by roles, with the caller's identity resolved from forwarded headers from an Identity Provider (IdP).

To retrieve information about the current authenticated user and their assigned application role, make a request to GET /admin/v1/me.

Error responses follow a standard envelope and include an error code prefixed with S2R-ADM-* for general admin errors or S2R-VAL-* for validation errors.

WSDL Import and Onboarding

The entry point for creating a new service is importing its WSDL contract. The import endpoints validate, parse, and persist the WSDL and its catalog of operations. The response provides a detailed onboarding preview, including backend suggestions, a readiness summary, sample payloads for each operation, and a comparison against any previous similar import.

Autopilot Import

The :autopilot variants provide a zero-touch onboarding experience by combining WSDL import and draft service generation into a single atomic call. These endpoints return a comprehensive response containing the import artifact preview, a draft service suggestion, the newly generated objects, and a publish-readiness assessment.

• POST /admin/v1/wsdl/import:autopilot: Imports a WSDL file and generates a service.
• POST /admin/v1/wsdl/import-url:autopilot: Imports a WSDL from a URL and generates a service.
• POST /admin/v1/wsdl/import-xml:autopilot: Imports WSDL from a raw XML payload and generates a service.
• POST /admin/v1/wsdl/import/{artifactId}:autopilot: Generates a service from an already-imported WSDL artifact.
• POST /admin/v1/wsdl/import-urls:autopilot: Batch imports multiple WSDLs from URLs.
• POST /admin/v1/wsdl/import-files:autopilot: Batch imports multiple WSDL files.

For more information, see the documentation on Zero-Touch Autopilot onboarding.

Services and Operations

These endpoints manage the core entities of the platform: logical services and their REST/SOAP operations.

Services

A service is a logical grouping for a set of related operations.

Operations and Mappings

Operations define the REST endpoint and its mapping to a backend SOAP operation. Mappings contain the transformation rules between REST and SOAP.

Backend Profiles and Credentials

A backend profile stores the configuration for connecting to a downstream SOAP service, including its endpoint URL, authentication method, and transport settings.

Backend Testing

These endpoints allow API publishers to test connectivity and transformations against a live backend before activating a service.

Supported authType values for backend profiles are none, basic, bearer, api_key_header, and oauth2_client_credentials. Mutual TLS can be enabled orthogonally by setting mtlsEnabled=true.

Other related endpoints include configuration for synthetic monitors (GET/POST /admin/v1/services/{serviceId}/synthetic-monitor) and management of reusable test datasets (GET/POST /admin/v1/services/{serviceId}/test-datasets, DELETE /admin/v1/test-datasets/{datasetId}).

Versioning, Activation, and Rollback

Service configurations are versioned and immutable once active. The standard workflow is to create a new draft version by cloning an existing version, modify the draft, validate its readiness, and then activate it.

The following diagram illustrates the service version lifecycle:

flowchart TD
    subgraph " "
        A[Active Version] -->|Clone| B(New Draft Version)
        B -->|Edit Mappings & Operations| B
        B -->|Check Readiness| C{Publish Readiness Check}
        C -->|Status: READY_TO_PUBLISH| D[Activate Version]
        C -->|Status: BLOCKED| B
        D --> E[New Active Version]
        A -->|Rollback| E
    end

OpenAPI Export

The platform can generate an OpenAPI v3 specification for any service version.

Settings and Roles

These endpoints manage global platform settings and user access control. Every change made via these endpoints emits an audit event.

Observability, Metrics, and Audit

The Admin API provides access to a wide range of observability data. To ensure fast query performance, most of these endpoints read from pre-computed aggregation tables rather than querying raw logs directly.

Troubleshooting

Common Error Responses

• 409 Conflict with code S2R-ADM-0410: This error indicates an attempt to modify an immutable resource or violate a state constraint. It is returned in the following situations:
  • Attempting to edit an operation or mapping on an active service version. Edits are only allowed on draft versions.
  • Attempting to hard-delete (:hard-delete) a service that is still active.
  • Attempting to activate (:activate) a service version whose publish-readiness status is BLOCKED.
  • Attempting to create a new draft version for a service that already has one.

All API errors are returned in a standard error envelope containing a machine-readable error code, typically prefixed with S2R-ADM-* or S2R-VAL-*. For a complete list, see the Error Code Reference.

See Also

• API Reference Overview
• Runtime API Reference
• Error Code Reference
• Role-Based Access Control (RBAC) and Roles
• Zero-Touch Autopilot Onboarding
• Publishing and Versioning a Service
• Observability Overview
• Audit Trail

All SOAP-to-REST docs