API Operation Management and Configuration

Overview

The OperationRepository is a data access component responsible for creating, reading, and updating API operations in the platform's database. It serves as the canonical source for an individual operation's configuration, including its REST endpoint mapping, backend SOAP details, runtime behaviors like timeouts and retries, and asynchronous processing settings.

This component solves the problem of persisting and managing the detailed configuration for each operation within a service version. It is primarily used by the administrative services of the platform. When an operation is updated, OperationRepository performs the database write and also triggers a critical side effect: synchronizing the operation's state with the s2r_runtime_route table. This ensures that changes made in the admin plane are correctly reflected in the runtime routing layer that handles live traffic.

How it works

The OperationRepository manages records in the s2r_operation database table. Each record represents a single API operation and contains all its configuration. The primary mechanism for modification is the update method, which orchestrates a series of validation, persistence, and synchronization steps.

Operation Update Flow

When an operation is updated, the following sequence occurs:

1. Pre-update Checks: The repository first retrieves the current state of the operation from the database. It then verifies that the operation's parent service version is in a mutable state (i.e., status is draft and it is not the active version). Attempts to modify an operation belonging to an active or non-draft version will fail.
2. Input Validation: All incoming parameters are validated and normalized. For example, the rest_method is converted to uppercase, rest_path is prefixed with a / if missing, and numeric values like timeout_ms are checked to be within allowed ranges.
3. Conditional Logic: The repository applies logic based on the execution_mode. If the mode is not async_callback, any callback-related fields are cleared. If the callback authentication mode is shared_secret, a callback_secret_ref is required.
4. Database Update: The s2r_operation table is updated with the new configuration values.
5. Runtime Route Synchronization: After the database update, the syncRuntimeRoute method is called to reflect the changes in the runtime routing table (s2r_runtime_route).

The following diagram illustrates the data flow for an operation update:

sequenceDiagram
    participant Admin Service
    participant Operation Repository
    participant Platform Database

    Admin Service->>Operation Repository: update(operationId, ...)
    Operation Repository->>Platform Database: Find operation by ID
    Operation Repository->>Platform Database: Check if service version is editable
    alt Not an editable draft version
        Operation Repository->>Admin Service: Throw IllegalStateException
    end
    Operation Repository->>Operation Repository: Validate and normalize parameters
    Operation Repository->>Platform Database: UPDATE s2r_operation table
    Operation Repository->>Operation Repository: syncRuntimeRoute(operationId)
    Note over Operation Repository,Platform Database: Synchronize with runtime routing table
    Operation Repository->>Platform Database: SELECT data for runtime route
    alt Route should be published
        Operation Repository->>Platform Database: Check for route collisions
        Operation Repository->>Platform Database: UPSERT into s2r_runtime_route table
    else Route should not be published
        Operation Repository->>Platform Database: DELETE from s2r_runtime_route table
    end
    Operation Repository->>Platform Database: Find updated operation by ID
    Operation Repository->>Admin Service: Return updated OperationRecord

Runtime Route Synchronization

The syncRuntimeRoute method ensures the runtime gateway has the correct routing information.

• Publication Rules: A route is published to the s2r_runtime_route table only if the operation is enabled, its parent service version is active, and the parent service's status is not disabled. If these conditions are not met, any existing entry for the operation is deleted from the runtime route table.
• Route Collision Guard: Before publishing a route, the system checks for collisions. A collision occurs if another service already uses the same combination of direction, environment, rest_method, and rest_path. This check prevents two services from unintentionally claiming the same endpoint.
• Upsert Logic: The synchronization uses an INSERT ... ON CONFLICT DO UPDATE (upsert) operation. This creates a new route if one doesn't exist or updates the existing one if the route path is already claimed by the same service. The conflict is detected on the unique key (direction, environment, rest_method, rest_path).
• Route Hashing: A SHA-256 hash (route_hash) is computed from the route's key components (direction, environment, method, path) to uniquely identify the route configuration.

Example

The primary interface for modification is the update method within the OperationRepository class. The source does not provide an HTTP endpoint example, but illustrates the programmatic call signature.

// This is a Java method signature, not a direct API endpoint.
public OperationRecord update(UUID operationId,
                              String restMethod,
                              String restPath,
                              Integer timeoutMs,
                              Integer retryCount,
                              String executionMode,
                              String callbackPath,
                              String callbackAuthMode,
                              String callbackSecretRef,
                              Integer asyncAckHttpStatus,
                              String actor)

Usage: To modify an operation, a caller would invoke this method with the operationId and a set of new configuration values. Any parameter provided as null will be ignored, and the existing value for that field will be retained. Upon successful execution, the method returns the complete, updated OperationRecord.

Configuration Parameters

The following parameters can be provided to the update method to configure an operation.

Data Model: OperationRecord

The OperationRecord represents the full configuration of an operation stored in the database.

API Reference

The OperationRepository class exposes the following public methods for managing operations.

Troubleshooting

When interacting with the OperationRepository, you may encounter the following exceptions:

See Also

• RouteCollisionGuard: A component responsible for preventing route conflicts between different services.
• WsdlRestRouteHeuristics: A component providing logic to determine if a generated GET operation should be converted to a POST.
• gov.specaria.service.ServiceDirection: A shared component for normalizing service direction values (e.g., PUBLISH, CONSUME).

All SOAP-to-REST docs