Backend Profile Management API

Overview

The Backend Profile Management API provides endpoints for configuring and managing BackendProfile resources. A backend profile defines how the API platform connects to a backend service, including its endpoint URL, authentication method, timeouts, and retry logic.

API publishers use this API to perform the following operations:

• Create, retrieve, update, and delete backend profiles for a specific service.
• Configure connection details such as timeouts, retries, and custom headers.
• Define authentication settings, including mTLS, Basic Auth, and various OAuth2 flows.
• Test connectivity and application-level integration with the configured backend.
• Manage related configurations for synthetic monitoring and test datasets.

All operations are scoped to a service and require appropriate authentication. The API provides detailed error responses and logs audit events for all state-changing operations.

How it Works

The controller exposes a set of RESTful endpoints that operate on backend profile resources stored in a repository.

Profile Lifecycle and Configuration

Backend profiles are managed on a per-service basis.

• Creation: A new profile is created via a POST request to /admin/v1/services/{serviceId}/backend-profiles. The request body contains all configuration parameters for the new profile.
• Update: An existing profile is modified via a PATCH request to /admin/v1/backend-profiles/{profileId}. The request body includes only the fields to be changed. Unspecified fields retain their current values.
• Credentials: The credentials field in create and update requests accepts a map containing plaintext secrets. The server only processes fields relevant to the selected authType and mtlsEnabled settings, strips any others, and encrypts the relevant values before persistence. The API never returns plaintext credentials; it only provides metadata indicating if credentials are set and when they were last updated.

OAuth2 Token Cache Invalidation

To ensure that the runtime gateway always uses fresh credentials, the API automatically invalidates the runtime's in-memory OAuth2 token cache when a profile's OAuth2 configuration is updated.

This invalidation is triggered under the following conditions for a profile with authType set to oauth2_client_credentials:

• The credentials field is updated.
• Any of the oauth2_* fields are modified.
• The authType is changed to or from oauth2_client_credentials.

The flush operation is asynchronous and non-blocking. This mechanism prevents the use of stale tokens, which might otherwise remain active for their full lifetime even after credentials have been rotated.

The following diagram illustrates the update flow with cache invalidation:

flowchart TD
    subgraph Update Backend Profile
        A[API Publisher] -- PATCH /admin/v1/backend-profiles/{profileId} --> B{Admin API};
        B -- Finds & updates profile --> C[Database];
        B -- Checks for OAuth2 changes --> D{OAuth2 Config Changed?};
        D -- Yes --> E[Async Flush Runtime Token Cache];
        D -- No --> F[Return 200 OK];
        E --> F;
        B -- Returns updated profile --> A;
    end

Backend Testing

The API provides several endpoints to test and validate a backend profile's configuration before and after deployment:

• Connection Test: Verifies basic network connectivity to the backend's endpointUrl and can optionally attempt to fetch a WSDL from the wsdlUrl.
• Application Test: Executes a full request-response cycle against the backend for a specific API operation. This allows testing with a custom request body.
• Generated Sample Test: Runs a suite of tests using system-generated sample payloads for one or more operations.

These test endpoints support "preview" configurations. An API publisher can provide temporary, unsaved overrides for the backend profile, operation settings, validation rules, and transforms directly in the test request. This allows for testing changes without modifying the active configuration.

Authorization

Most operations can be performed by authenticated users with standard permissions. However, configuring certain sensitive authentication methods requires elevated privileges.

API Reference

Backend Profile Endpoints

List Backend Profiles

Lists all backend profiles for a given service.

GET /admin/v1/services/{serviceId}/backend-profiles

Path Parameters

Responses

• 200 OK: Returns a JSON array of backend profile objects.
• 404 Not Found: If the service does not exist.

Create Backend Profile

Creates a new backend profile for a service.

POST /admin/v1/services/{serviceId}/backend-profiles

Path Parameters

Request Body

A JSON object with the structure of CreateBackendProfileRequest. See the Request Body Payloads section for details.

Responses

• 200 OK: Returns the created backend profile object.
• 400 Bad Request: If the request payload is invalid (e.g., S2R-VAL-0401) or the OAuth2 configuration is invalid (S2R-VAL-0405).
• 403 Forbidden: If attempting to use workload_identity_federation without ADMIN role (S2R-ADM-0403).

Update Backend Profile

Updates an existing backend profile. Only the fields provided in the request body are modified.

PATCH /admin/v1/backend-profiles/{profileId}

Path Parameters

Request Body

A JSON object with the structure of PatchBackendProfileRequest. See the Request Body Payloads section for details.

Responses

• 200 OK: Returns the updated backend profile object.
• 400 Bad Request: If the request payload is invalid (S2R-VAL-0401) or the OAuth2 configuration is invalid (S2R-VAL-0405).
• 403 Forbidden: If attempting to modify a profile to use workload_identity_federation without ADMIN role (S2R-ADM-0403).
• 404 Not Found: If no backend profile with the given profileId exists (S2R-ADM-0404).

Delete Backend Profile

Deletes a backend profile.

DELETE /admin/v1/backend-profiles/{profileId}

Path Parameters

Responses

• 200 OK: Returns a DeleteBackendProfileResponse object confirming the deletion.
• 400 Bad Request: If the profile cannot be deleted (e.g., it is in use) (S2R-VAL-0401).
• 404 Not Found: If no backend profile with the given profileId exists (S2R-ADM-0404).

Testing Endpoints

Test Backend Connection

Performs a connectivity test against the backend profile's endpoint.

POST /admin/v1/backend-profiles/{profileId}:test-connection

Path Parameters

Request Body

An optional JSON object with the following structure:

Responses

• 200 OK: Returns a JSON object with the test results.
• 404 Not Found: If no backend profile with the given profileId exists (S2R-ADM-0404).

Run Application Test

Executes a full application-level test against the backend using a provided request.

POST /admin/v1/backend-profiles/{profileId}:test-application

Path Parameters

Request Body

A JSON object with the structure of ApplicationTestRequest. The operationId field is required. See the Request Body Payloads section for details.

Responses

• 200 OK: Returns a JSON object with the test results, including the backend's response.
• 400 Bad Request: If the request is invalid, such as a missing operationId (S2R-VAL-0401).
• 404 Not Found: If no backend profile with the given profileId exists (S2R-ADM-0404).

Run REST Test

A variant of the application test. If requestFormat is not provided, it defaults to json.

POST /admin/v1/backend-profiles/{profileId}:test-rest

Path Parameters

Request Body

A JSON object with the structure of ApplicationTestRequest. The operationId field is required. See the Request Body Payloads section for details.

Responses

• 200 OK: Returns a JSON object with the test results.
• 400 Bad Request: If the request is invalid (S2R-VAL-0401).
• 404 Not Found: If no backend profile with the given profileId exists (S2R-ADM-0404).

Run Generated Sample Tests

Executes tests against the backend using generated sample requests.

POST /admin/v1/backend-profiles/{profileId}:test-generated-samples

Path Parameters

Request Body

An optional JSON object with the structure of GeneratedSampleTestRequest. See the Request Body Payloads section for details.

Responses

• 200 OK: Returns a JSON object with the results of the sample tests.
• 400 Bad Request: If the request is invalid (S2R-VAL-0401).
• 404 Not Found: If no backend profile with the given profileId exists (S2R-ADM-0404).

List Test Previews

Retrieves recent test previews for a backend profile.

GET /admin/v1/backend-profiles/{profileId}/test-previews

Path Parameters

Query Parameters

Responses

• 200 OK: Returns a JSON array of test preview objects.
• 404 Not Found: If no backend profile with the given profileId exists (S2R-ADM-0404).

Synthetic Monitor Endpoints

Get Synthetic Monitor Configuration

Retrieves the synthetic monitor configuration for a service.

GET /admin/v1/services/{serviceId}/synthetic-monitor

Path Parameters

Responses

• 200 OK: Returns the synthetic monitor configuration object, or null if not configured.

Save Synthetic Monitor Configuration

Creates or updates the synthetic monitor configuration for a service.

POST /admin/v1/services/{serviceId}/synthetic-monitor

Path Parameters

Request Body

A JSON object with the structure of SaveSyntheticMonitorRequest. The backendProfileId and operationId fields are required. See the Request Body Payloads section for details.

Responses

• 200 OK: Returns the saved synthetic monitor configuration object.
• 400 Bad Request: If the request is invalid, such as missing backendProfileId or operationId (S2R-VAL-0401).

Test Dataset Endpoints

List Test Datasets

Lists all test datasets for a service.

GET /admin/v1/services/{serviceId}/test-datasets

Path Parameters

Responses

• 200 OK: Returns a JSON array of test dataset objects.
• 400 Bad Request: If the serviceId is invalid (S2R-VAL-0401).

Save Test Dataset

Creates or updates a test dataset for a service.

POST /admin/v1/services/{serviceId}/test-datasets

Path Parameters

Request Body

A JSON object with the structure of SaveTestDatasetRequest. The datasetName field is required. See the Request Body Payloads section for details.

Responses

• 200 OK: Returns the saved test dataset object.
• 400 Bad Request: If the request is invalid, such as a missing datasetName (S2R-VAL-0401).

Delete Test Dataset

Deletes a test dataset.

DELETE /admin/v1/test-datasets/{datasetId}

Path Parameters

Responses

• 200 OK: Returns the deleted test dataset object.
• 400 Bad Request: If the datasetId is invalid or not found (S2R-VAL-0401).

Request Body Payloads

CreateBackendProfileRequest & PatchBackendProfileRequest

These objects define the configuration of a backend profile. For PATCH requests, only include the fields you wish to change.

| soapVersion | String | No | The SOAP version (e.g., "1.1", "1.2"). | --- | --- | --- | | connectionTimeoutMs | Integer | No | Connection timeout in milliseconds. | readTimeoutMs | Integer | No | Read timeout in milliseconds. | retryCount | Integer | No | Number of times to retry a failed request.

| retryBackoffMs | Integer | No | The delay in milliseconds between retries. | --- | --- | --- | | routingPriority | Integer | No | Priority for routing when multiple active profiles exist. The source does not specify the range or behavior. | routingWeight | Integer | No | Weight for routing when multiple active profiles exist. The source does not specify the range or behavior. | active | Boolean | No | Whether this profile is active for routing. | extraHeaders | Array<ExtraHeader> | No | A list of custom HTTP headers to add to requests to the backend. See ExtraHeader structure below.

All SOAP-to-REST docs