API Operation Management

Overview

The Operation Repository is a data access component responsible for managing individual API operations. An operation is a single function within an API service version, defined by its SOAP and REST characteristics, execution behavior, and data schemas. This component provides the low-level interface for creating, retrieving, and updating operations in the s2r_operation database table.

This repository is a critical part of the administration service. It is called by higher-level services to persist changes to an operation's configuration. Its primary responsibilities include:

• Retrieving operation details and data contracts (schemas).
• Applying configuration updates, such as changing the REST endpoint, timeout, or execution mode.
• Managing request and response schemas.
• Synchronizing an operation's configuration with the s2r_runtime_route table, which makes the REST endpoint live and routable by the gateway.

Every database query is automatically scoped to the current tenant, ensuring that modifications for one tenant cannot affect another.

How it Works

The repository uses direct SQL queries via JdbcTemplate to interact with the database. The core logic revolves around updating an operation's record and then synchronizing that change to the runtime routing layer.

Operation Update Flow

When an operation is updated via the update method, the system performs the following sequence:

1. Fetch Current State: The repository first retrieves the existing OperationRecord from the database.
2. Check Mutability: It verifies that the operation belongs to a service version that is in a draft state and not active. Active service versions are immutable. If the version is not editable, the update is rejected with an IllegalStateException.
3. Normalize and Validate Inputs: Each provided parameter (e.g., restMethod, timeoutMs) is validated against business rules. For example, timeout_ms must be between 1 and 60,000, and rest_method must be one of the allowed HTTP methods.
4. Apply Changes: The validated parameters are used to construct an UPDATE statement for the s2r_operation table. If an update parameter is not provided (is null), the existing value is preserved.
5. Synchronize Runtime Route: After the database record is updated, the syncRuntimeRoute method is called to reflect the changes in the runtime environment.

Runtime Route Synchronization

The syncRuntimeRoute method is a critical process that makes an operation's REST endpoint available to API consumers.

flowchart TD
    subgraph syncRuntimeRoute Flow
        A[Start] --> B(Fetch operation, version, and service data);
        B -- Not found --> B_end(End);
        B -- Found --> C(Delete any existing route for this operation);
        C --> D{Should publish route?<br/>(Operation enabled AND<br/>Version active AND<br/>Service not disabled)};
        D -- No --> D_end(End);
        D -- Yes --> E(Check for route collision with other services);
        E -- Collision found --> F(Fail with error);
        E -- No collision --> G(Calculate route hash);
        G --> H(Upsert route into runtime routing table);
        H --> H_end(End);
    end

This flow ensures that:

• Only operations that are part of an active, enabled service are published as live routes.
• Updates to an operation's rest_method or rest_path are correctly reflected in the routing table.
• Route conflicts are prevented. The system checks if the proposed route (direction, environment, rest_method, rest_path) is already in use by a different service. If a collision is detected, the operation update fails.
• A unique route_hash (SHA-256) is generated for the route to uniquely identify it.
• The s2r_runtime_route table is updated atomically using an INSERT ... ON CONFLICT DO UPDATE (upsert) statement, which claims the route for the current operation.

Asynchronous Callback Configuration

The repository includes specific logic for configuring asynchronous operations (execution_mode = 'async_callback').

• Authentication Mode: The callback_auth_mode determines how the platform authenticates incoming callback requests. It defaults to shared_secret for security. To accept unauthenticated callbacks, it must be explicitly set to none.
• Secret Management: If callback_auth_mode is shared_secret, a callback_secret_ref is required. To prevent accidental deletion, the callback_secret_ref is write-only. If an update request provides a blank or null value for the secret, the previously stored secret is retained. A new value must be explicitly provided to change it.
• Cleanup: If an operation's execution_mode is changed from async_callback to sync, all callback-related fields (callback_path, callback_secret_ref) are automatically cleared (nullified).

Key Procedures

Backfill GET Operations

The backfillGeneratedGetOperations method provides a mechanism to correct misconfigured operations. It identifies all operations that were generated as GET requests and, based on heuristics from WsdlRestRouteHeuristics, determines if they should have been POST requests (e.g., if they have a request body schema).

When executed, it performs the following steps for each candidate operation:

1. Fetches all GET operations within the current tenant.
2. For each operation, it checks if it meets the criteria to be converted to POST using WsdlRestRouteHeuristics.shouldForcePost.
3. If it meets the criteria, it updates the operation's rest_method to POST.
4. It then calls syncRuntimeRoute to update the corresponding runtime route, effectively changing the live endpoint from GET to POST.
5. The method returns a count of the total number of operations that were updated.

API Reference

The repository exposes the following methods for managing operations.

update

Updates the configuration of a single operation.

OperationRecord update(UUID operationId,
                       String restMethod,
                       String restPath,
                       Integer timeoutMs,
                       Integer retryCount,
                       String executionMode,
                       String callbackPath,
                       String callbackAuthMode,
                       String callbackSecretRef,
                       Integer asyncAckHttpStatus,
                       String actor)

Parameters

Returns

An OperationRecord object representing the updated state of the operation.

updateSchemas

Updates the JSON request and response schemas for a single operation.

OperationContractRecord updateSchemas(UUID operationId,
                                      Map<String, Object> requestSchema,
                                      Map<String, Object> responseSchema,
                                      String actor)

Parameters

Returns

An OperationContractRecord object representing the updated state of the operation's schemas.

Other Methods

Data Models

OperationRecord

Represents the full configuration of an operation.

OperationContractRecord

Represents the data contract of an operation, focusing on its schemas.

Troubleshooting

See Also

• Service Version Management
• Runtime Routing
• Service Direction Configuration

All SOAP-to-REST docs