Manage API Operations

Use the Admin API to configure REST-to-SOAP operations, including timeouts, retries, validation rules, transformation rules, and example payloads.

Overview

The Operations API provides administrative endpoints for configuring the behavior of individual API operations. An "operation" represents a single mapping from a REST endpoint to a backend SOAP operation. API publishers use these endpoints to manage the runtime characteristics of each operation exposed by the platform.

This API allows you to:

List all operations associated with a specific service version.
Update an operation's core properties, such as its REST method and path, backend timeout, and retry policies.
Configure asynchronous processing behavior, including callback details.
Manage data validation rule overrides for request and response payloads.
Define and update request and response transformation rules.
Retrieve example request and response payloads, sourced from either observed traffic or the original WSDL contract.

These endpoints are typically consumed by administrative UIs or automation scripts to provision and maintain API configurations. All changes made via this API are audited.

How It Works

The platform can provide example payloads for any given operation to aid in testing and integration. The retrieval logic for these examples follows a specific priority order to deliver the most relevant content available.

Example Payload Retrieval

When an example payload is requested via GET /admin/v1/operations/{operationId}/examples, the system attempts to find a payload in the following order:

Learned Example: The system first searches for real request or response payloads captured from live traffic. This is considered the highest quality source. The lookup process first computes a canonical service_backend_key from the operation's default backend URL. It then queries for traffic matching this key and the operation's SOAP name. If this preferred lookup yields no results, it attempts a fallback search using the service_id.
WSDL-Derived Sample: If no learned example is found, the system generates a sample JSON payload based on the operation's contract schema (from the WSDL). This provides a structurally correct example based on the defined data types.
Placeholder: If the contract cannot be used to generate a sample (e.g., due to an error or missing schema), a minimal placeholder JSON object is returned, indicating that no example is available.

The following diagram illustrates this decision flow:

flowchart TD
    subgraph "Example Retrieval Logic"
        A[API consumer requests example] --> B{GET /.../examples};
        B --> C{Kind: 'request' or 'response'?};
        C -- "request" --> D[Find learned request payload];
        C -- "response" --> E[Find learned response payload];
        D --> F{Payload found?};
        E --> F;
        F -- Yes --> G[Return learned XML payload<br/>(source: "learned")];
        F -- No --> H{WSDL contract available?};
        H -- Yes --> I[Generate JSON sample from schema];
        I --> J{Generation successful?};
        J -- Yes --> K[Return generated JSON payload<br/>(source: "wsdl")];
        J -- No --> L[Return empty placeholder<br/>(source: "none")];
        H -- No --> L;
        G --> M[Done];
        K --> M;
        L --> M;
    end

A similar lookup strategy, preferring service_backend_key and falling back to service_id, is used when retrieving a list of learned examples via the GET /admin/v1/operations/{operationId}/learned-examples endpoint.

API Reference

These endpoints manage operations and their associated rules and examples.

List Operations

Lists all operations for a specific service version.

GET /admin/v1/services/{serviceId}/versions/{versionId}/operations

Path Parameters

Name	Type	Required	Description
`serviceId`	UUID	Yes	The unique identifier of the service.
`versionId`	UUID	Yes	The unique identifier of the service version.

Responses

200 OK: A JSON array of OperationRecord objects. The source does not fully define the structure of OperationRecord, but it includes fields for REST configuration, execution behavior, and SOAP metadata.
404 Not Found: If the service or version does not exist.

Update an Operation

Updates one or more configuration properties of a single operation. Only the fields provided in the request body will be updated.

PATCH /admin/v1/operations/{operationId}

Path Parameters

Name	Type	Required	Description
`operationId`	UUID	Yes	The unique identifier of the operation to update.

Request Body

The request body is a JSON object containing the fields to update. At least one field must be provided.

Field	Type	Required	Description
`restMethod`	String	No	The HTTP method for the REST endpoint (e.g., `GET`, `POST`).
`restPath`	String	No	The path for the REST endpoint, which may include path variables (e.g., `/users/{id}`).
`timeoutMs`	Integer	No	The timeout in milliseconds for waiting on the backend SOAP service.
`retryCount`	Integer	No	The number of times to retry a failed request to the backend.
`executionMode`	String	No	The execution mode for the operation. The source does not specify possible values.
`callbackPath`	String	No	The path for the callback in asynchronous execution mode.
`callbackAuthMode`	String	No	The authentication mode for the callback. The source does not specify possible values.
`callbackSecretRef`	String	No	A reference to a secret used for callback authentication.
`asyncAckHttpStatus`	Integer	No	The HTTP status code to return immediately as an acknowledgment in asynchronous mode.

Example: Update an Operation's Timeout and Retry Count

This example updates an operation to have a 5-second timeout and to retry failed requests twice.

curl -X PATCH \
  'https://<platform-host>/admin/v1/operations/a1b2c3d4-e5f6-7890-1234-567890abcdef' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <API_TOKEN>' \
  -d '{
    "timeoutMs": 5000,
    "retryCount": 2
  }'

A successful request returns a 200 OK with the full, updated OperationRecord object in the response body.

Responses

200 OK: The operation was successfully updated. The response body contains the updated OperationRecord.
400 Bad Request: The request was invalid. This can occur if the request body is empty or contains invalid values. The response body will contain an error object with code S2R-VAL-0401.
404 Not Found: The specified operationId does not exist. The response body will contain an error object with code S2R-ADM-0404.
409 Conflict: The update could not be completed due to a conflict, such as a duplicate restPath and restMethod combination or an invalid state transition. The response body will contain an error object with code S2R-ADM-0409 or S2R-ADM-0410.

Get Validation Rules

Retrieves the configured validation rule overrides for an operation.

GET /admin/v1/operations/{operationId}/validation-rules

Path Parameters

Name	Type	Required	Description
`operationId`	UUID	Yes	The unique identifier of the operation.

Responses

200 OK: Success. The response body contains an object describing the validation rules. The source does not specify the exact structure of this object.
404 Not Found: The specified operationId does not exist. The response body will contain an error object with code S2R-ADM-0404.

Update a Validation Rule

Creates or updates a validation rule override for a specific field in an operation's request or response.

PATCH /admin/v1/operations/{operationId}/validation-rules

Path Parameters

Name	Type	Required	Description
`operationId`	UUID	Yes	The unique identifier of the operation.

Request Body

The request body is a JSON object specifying the rule to update.

Field	Type	Required	Description
`side`	String	Yes	The part of the message the rule applies to. The source does not specify possible values (e.g., "request", "response").
`fieldPath`	String	Yes	A path expression identifying the field to validate.
`enumValues`	Array of Strings	No	A list of allowed string values for the field.
`pattern`	String	No	A regular expression pattern the field's value must match.
`length`	Integer	No	The exact required length for a string or list.
`minLength`	Integer	No	The minimum required length for a string or list.
`maxLength`	Integer	No	The maximum allowed length for a string or list.
`minInclusive`	String	No	The minimum allowed value (inclusive) for a numeric or date field.
`maxInclusive`	String	No	The maximum allowed value (inclusive) for a numeric or date field.
`minExclusive`	String	No	The minimum allowed value (exclusive) for a numeric or date field.
`maxExclusive`	String	No	The maximum allowed value (exclusive) for a numeric or date field.
`totalDigits`	Integer	No	The maximum number of digits for a numeric field.
`fractionDigits`	Integer	No	The maximum number of fractional digits for a numeric field.

Responses

200 OK: The rule was successfully updated. The response body contains the updated rule definition.
400 Bad Request: The request was invalid. The response body will contain an error object with code S2R-VAL-0401.
409 Conflict: The update could not be applied due to an invalid state. The response body will contain an error object with code S2R-ADM-0410.

Get Transformation Rules

Retrieves the request and response transformation rules for an operation.

GET /admin/v1/operations/{operationId}/transform-rules

Path Parameters

Name	Type	Required	Description
`operationId`	UUID	Yes	The unique identifier of the operation.

Responses

200 OK: Success. The response body contains an object with requestRules and responseRules arrays. The source does not define the structure of the rule objects within these arrays.
404 Not Found: The specified operationId does not exist. The response body will contain an error object with code S2R-ADM-0404.

Replace Transformation Rules

Replaces all existing transformation rules for an operation with the set provided in the request.

IMPORTANT

This is a PUT operation, which is destructive. Any existing rules not included in the request will be deleted. To clear all rules, send a request with empty or null requestRules and responseRules arrays.

PUT /admin/v1/operations/{operationId}/transform-rules

Path Parameters

Name	Type	Required	Description
`operationId`	UUID	Yes	The unique identifier of the operation.

Request Body

The request body is a JSON object containing arrays of rules.

Field	Type	Required	Description
`requestRules`	Array of `OperationTransformRuleRecord`	No	An array of transformation rules to apply to the request.
`responseRules`	Array of `OperationTransformRuleRecord`	No	An array of transformation rules to apply to the response.

NOTE

The source does not define the structure of the OperationTransformRuleRecord objects.

Responses

200 OK: The rules were successfully replaced. The response body contains the new set of rules.
400 Bad Request: The request was invalid. The response body will contain an error object with code S2R-VAL-0401.

Get an Example Payload

Retrieves a single example payload for an operation's request or response. The system follows a defined priority to find the best available example (see How It Works).

GET /admin/v1/operations/{operationId}/examples

Path Parameters

Name	Type	Required	Description
`operationId`	UUID	Yes	The unique identifier of the operation.

Query Parameters

Name	Type	Default	Required	Description
`kind`	String	`request`	No	The type of example to retrieve. Must be `request` or `response`.

Responses

200 OK: Success. The response body is a JSON object with the following fields:
- kind: The type of example (request or response).
- source: The origin of the example (learned, wsdl, or none).
- contentType: The content type of the payload (e.g., application/xml, application/json).
- payload: The example payload as a string.
400 Bad Request: The kind parameter is invalid. The response body will contain an error object with code S2R-VAL-0401.
404 Not Found: The specified operationId does not exist. The response body will contain an error object with code S2R-ADM-0404.

Get Learned Examples

Retrieves a list of learned examples for an operation, captured from observed traffic.

GET /admin/v1/operations/{operationId}/learned-examples

Path Parameters

Name	Type	Required	Description
`operationId`	UUID	Yes	The unique identifier of the operation.

Query Parameters

Name	Type	Default	Required	Description
`limit`	Integer	`5`	No	The maximum number of examples to return. The value is capped between 1 and 25.

Responses

200 OK: Success. The response body is a JSON object containing:
- examples: An array of learned example objects.
- serviceBackendKey: The canonical backend key used for the lookup.

Each object in the examples array has the following structure:

Field	Type	Description
`id`	UUID	The unique ID of the learned example record.
`soapAction`	String	The `SOAPAction` header from the captured request.
`soapOperationName`	String	The name of the SOAP operation.
`backendHost`	String	The hostname of the backend service that was called.
`backendPort`	Integer	The port of the backend service.
`backendUri`	String	The URI path of the backend service.
`clientIp`	String	The IP address of the original client.
`frontVirtualServer`	String	The name of the frontend virtual server that received the request.
`backVirtualServer`	String	The name of the backend virtual server that processed the request.
`frontendHost`	String	The `Host` header from the original frontend request.
`frontendUri`	String	The URI from the original frontend request.
`instanceId`	UUID	The identifier of the traffic-capturing instance.
`firstSeenAt`	String	The timestamp (ISO 8601) when this example was first seen.
`lastSeenAt`	String	The timestamp (ISO 8601) when this example was last seen.
`seenCount`	Integer	The number of times this example has been observed.
`xml`	String	The raw XML payload of the SOAP request.
`responsePayload`	String	The raw payload of the SOAP response.
`requestHeaders`	Object	A JSON object representing the HTTP headers of the request.
`responseHeaders`	Object	A JSON object representing the HTTP headers of the response.
`rest`	Object	A JSON projection of the SOAP request body. `null` if parsing fails.
`restError`	String	An error message if the SOAP request body could not be projected to JSON.
`restResponse`	Object	A JSON projection of the SOAP response body. `null` if parsing fails.
`restResponseError`	String	An error message if the SOAP response body could not be projected to JSON.

404 Not Found: The specified operationId does not exist. The response body will contain an error object with code S2R-ADM-0404.

Troubleshooting

When an API call fails, the response body will contain a JSON object with an error field detailing the problem.

Error Code	HTTP Status	Meaning
`S2R-VAL-0401`	400 Bad Request	The request is invalid. This may be due to missing required fields, invalid parameter values (e.g., an incorrect `kind` for examples), or an empty request body for a `PATCH` request.
`S2R-ADM-0404`	404 Not Found	The specified resource (e.g., an operation) could not be found.
`S2R-ADM-0409`	409 Conflict	The requested update conflicts with an existing resource. For example, attempting to set a `restMethod` and `restPath` that are already in use by another operation.
`S2R-ADM-0410`	409 Conflict	The requested update is not allowed due to the current state of the resource.

Tagsreference

All SOAP-to-REST docs

Loading…