Backend Profile Management API

Overview

The Backend Profile Management API provides administrative endpoints for configuring how the platform connects to backend services. A backend profile is a collection of settings that defines a specific backend endpoint, including its URL, authentication method, timeout and retry policies, and routing information.

API publishers use these endpoints to create, view, update, and delete backend profiles associated with their services. The API also provides powerful testing capabilities to validate connectivity and application-level behavior against a backend before or after deploying changes. This includes running tests with temporary "preview" configurations that override a saved profile's settings.

This controller is a key component of the Admin API. It interacts with the persistence layer to manage profile records and coordinates with various testing and configuration services. When OAuth2 client credentials are updated, it automatically triggers a flush of the runtime's in-memory token cache to ensure new credentials are used immediately.

How it Works

Backend profiles are managed on a per-service basis. The core lifecycle is handled by standard CRUD (Create, Read, Update, Delete) operations. The update (PATCH) operation includes a specific mechanism to handle authentication credential changes securely and efficiently.

When an API publisher updates a backend profile that uses OAuth2 client credentials, the system must ensure that any in-memory access tokens in the runtime are invalidated. Stale tokens could otherwise remain in use until they expire.

The following diagram illustrates the sequence for updating a profile and flushing the OAuth2 token cache:

sequenceDiagram
    participant API Publisher
    participant Admin API
    participant Backend Profile Repository
    participant Runtime OAuth2 Cache

    API Publisher->>+Admin API: PATCH /admin/v1/backend-profiles/{profileId}
    Admin API->>+Backend Profile Repository: findById(profileId)
    Backend Profile Repository-->>-Admin API: Return existing profile
    Admin API->>+Backend Profile Repository: update(profileId, changes)
    Backend Profile Repository-->>-Admin API: Return updated profile
    
    alt OAuth2 credentials changed
        Admin API->>Admin API: shouldFlushOauth2() is true
        Admin API-->>Runtime OAuth2 Cache: flushAsync(profileId)
    end

    Admin API-->>-API Publisher: 200 OK with updated profile

This process is triggered by the PATCH /admin/v1/backend-profiles/{profileId} endpoint.

1. The Admin API receives the update request.
2. It retrieves the current state of the profile from the BackendProfileRepository.
3. It persists the changes by calling backendProfileRepository.update().
4. The shouldFlushOauth2() internal check determines if a cache flush is needed. A flush is triggered if the profile's authType is or was oauth2_client_credentials and any of the following are true:
   • New credentials were provided in the credentials field.
   • The authType was changed.
   • The oauth2TokenEndpoint, oauth2ClientId, oauth2Scope, or oauth2ExtraParams fields were modified.
5. If a flush is required, the Admin API sends an asynchronous flushAsync request to the runtime component responsible for caching OAuth2 tokens. This is a "fire-and-forget" operation.
6. Finally, the Admin API returns the updated backend profile object to the caller. The response payload redacts plaintext credentials, showing only metadata about when they were last set.

Example: Creating a Backend Profile

This example shows how to create a new backend profile for a service. The request defines the backend's URL, authentication type, and connection settings.

Send a POST request to /admin/v1/services/{serviceId}/backend-profiles:

{
  "profileName": "Primary SOAP Backend",
  "endpointUrl": "https://backend.example.com/service/v2",
  "wsdlUrl": "https://backend.example.com/service/v2?wsdl",
  "authType": "http_basic",
  "soapVersion": "1.2",
  "connectionTimeoutMs": 5000,
  "readTimeoutMs": 30000,
  "retryCount": 2,
  "active": true,
  "credentials": {
    "username": "service-user",
    "password": "<SECRET_PASSWORD>"
  },
  "setAsDefault": true
}

A successful request will return a 200 OK status code and a JSON body containing the newly created backend profile object, including its system-generated id.

API Endpoints

Backend Profile Management

List Backend Profiles

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

  Retrieves a list of all backend profiles for a given service.

  Path Parameters

  Name	Type	Description
  serviceId	UUID	The unique identifier of the service.

  Responses

  • 200 OK: Returns a JSON array of backend profile objects.

Create a Backend Profile

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

  Creates a new backend profile for a service.

  Path Parameters

  Name	Type	Description
  serviceId	UUID	The unique identifier of the service.

  Request Body

  • CreateBackendProfileRequest: A JSON object containing the profile's configuration. See the CreateBackendProfileRequest table for details.

  Responses

  • 200 OK: Returns the created backend profile object.
  • 400 Bad Request: If the request is invalid (e.g., bad OAuth2 configuration). See S2R-VAL-0405 and S2R-VAL-0401 in the Troubleshooting section.

Update a Backend Profile

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

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

  IMPORTANT

  When updating a profile that uses oauth2_client_credentials, any change to authType, oauth2TokenEndpoint, oauth2ClientId, oauth2Scope, oauth2ExtraParams, or providing new credentials will trigger an asynchronous flush of the runtime's OAuth2 token cache.

  Path Parameters

  Name	Type	Description
  profileId	UUID	The unique identifier of the backend profile.

  Request Body

  • PatchBackendProfileRequest: A JSON object containing the fields to update. See the PatchBackendProfileRequest table for details.

  Responses

  • 200 OK: Returns the updated backend profile object.
  • 400 Bad Request: If the request is invalid. See S2R-VAL-0405 and S2R-VAL-0401 in the Troubleshooting section.
  • 404 Not Found: If the profileId does not exist.

Delete a Backend Profile

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

  Deletes a backend profile.

  Path Parameters

  Name	Type	Description
  profileId	UUID	The unique identifier of the backend profile.

  Responses

  • 200 OK: Returns a DeleteBackendProfileResponse object confirming the deletion.
  • 400 Bad Request: If the deletion is not possible (e.g., profile is in use).
  • 404 Not Found: If the profileId does not exist.

Testing and Diagnostics

Test Backend Connection

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

  Performs a basic connectivity test against the backend profile's endpointUrl. It can also optionally fetch and parse the wsdlUrl for SOAP services.

  Path Parameters

  Name	Type	Description
  profileId	UUID	The unique identifier of the backend profile.

  Request Body

  • ConnectivityTestRequest (optional): A JSON object specifying test options.

  Responses

  • 200 OK: Returns a JSON object with the results of the connectivity test.
  • 404 Not Found: If the profileId does not exist.

Run an Application Test

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

  Executes a full application-level test against a specific operation, sending a request to the backend and capturing the response. This endpoint allows previewing changes to the backend profile, operation settings, validation rules, and transformations without saving them.

  Path Parameters

  Name	Type	Description
  profileId	UUID	The unique identifier of the backend profile.

  Request Body

  • ApplicationTestRequest: A JSON object containing the test parameters and preview configurations.

  Responses

  • 200 OK: Returns a JSON object with the detailed results of the application test.
  • 400 Bad Request: If required fields like operationId are missing.
  • 404 Not Found: If the profileId does not exist.

Run a REST Test

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

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

  Path Parameters

  Name	Type	Description
  profileId	UUID	The unique identifier of the backend profile.

  Request Body

  • ApplicationTestRequest: A JSON object containing the test parameters.

  Responses

  • 200 OK: Returns a JSON object with the test results.
  • 400 Bad Request: If required fields are missing.
  • 404 Not Found: If the profileId does not exist.

Test with Generated Samples

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

  Runs tests using system-generated sample request data. This can target a specific operation or an entire API version. It also supports previewing configuration changes.

  Path Parameters

  Name	Type	Description
  profileId	UUID	The unique identifier of the backend profile.

  Request Body

  • GeneratedSampleTestRequest (optional): A JSON object to customize the sample generation and test execution.

  Responses

  • 200 OK: Returns a JSON object with the results of the sample-based tests.
  • 400 Bad Request: If the request contains invalid arguments.
  • 404 Not Found: If the profileId does not exist.

List Test Previews

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

  Retrieves a list of recent test previews executed against a backend profile.

  Path Parameters

  Name	Type	Description
  profileId	UUID	The unique identifier of the backend profile.

  Query Parameters

  Name	Type	Default	Description
  limit	Integer	20	The maximum number of recent previews to return.

  Responses

  • 200 OK: Returns a JSON array of test preview results.
  • 404 Not Found: If the profileId does not exist.

Synthetic Monitoring

Get Synthetic Monitor Configuration

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

  Retrieves the synthetic monitoring configuration for a service.

  Path Parameters

  Name	Type	Description
  serviceId	UUID	The unique identifier of the service.

  Responses

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

Save Synthetic Monitor Configuration

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

  Creates or updates the synthetic monitoring configuration for a service.

  Path Parameters

  Name	Type	Description
  serviceId	UUID	The unique identifier of the service.

  Request Body

  • SaveSyntheticMonitorRequest: A JSON object defining the monitor's settings.

  Responses

  • 200 OK: Returns the saved synthetic monitor configuration object.
  • 400 Bad Request: If backendProfileId or operationId are missing.

Test Datasets

List Test Datasets

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

  Retrieves all test datasets for a service.

  Path Parameters

  Name	Type	Description
  serviceId	UUID	The unique identifier of the service.

  Responses

  • 200 OK: Returns a JSON array of test dataset objects.
  • 400 Bad Request: If the service ID is invalid.

Save a Test Dataset

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

  Creates or updates a named test dataset for a service.

  Path Parameters

  Name	Type	Description
  serviceId	UUID	The unique identifier of the service.

  Request Body

  • SaveTestDatasetRequest: A JSON object defining the dataset.

  Responses

  • 200 OK: Returns the saved test dataset object.
  • 400 Bad Request: If datasetName is missing or the request is otherwise invalid.

Delete a Test Dataset

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

  Deletes a test dataset.

  Path Parameters

  Name	Type	Description
  datasetId	UUID	The unique identifier of the test dataset.

  Responses

  • 200 OK: Returns the deleted test dataset object.
  • 400 Bad Request: If the deletion fails.

Payloads and Data Structures

Backend Profile Object

This is the primary object representing a backend profile, returned by GET, POST, and PATCH endpoints.

CreateBackendProfileRequest / PatchBackendProfileRequest

These payloads are used for creating and updating backend profiles. All fields are optional for PATCH.

ExtraHeader Object

OAuth2ExtraParam Object

ApplicationTestRequest Object

DeleteBackendProfileResponse Object

Troubleshooting

See Also

• Synthetic Monitoring: Configure automated health and functionality checks for your services using the synthetic monitor endpoints.
• Test Datasets: Manage reusable sets of test data for application testing.
• Contract Validation Overrides: Temporarily modify validation rules during testing using the previewValidationRules field.
• Operation Transformation Rules: Preview the effect of request and response transformations using the previewRequestTransformRules and previewResponseTransformRules fields.

All SOAP-to-REST docs