Service Version Management

Overview

The Service Version Management component provides the data-layer logic for the lifecycle of an API service's versions. It enables API publishers to iterate on a service by creating new, isolated "draft" versions, modifying them, and then activating a chosen version to handle live traffic.

This component solves the problem of safely evolving an API without disrupting existing consumers. It ensures that the transition from one version to another is an atomic operation, including the critical step of updating the API Gateway's routing table.

The primary functions are:

• Listing and retrieving version records for a service.
• Creating draft versions by cloning an existing version.
• Activating a version, which makes it the live, consumer-facing version.
• Associating a version with its source OpenAPI specification for traceability.

This component is an internal part of the administrative platform, typically invoked by higher-level services that expose this functionality through the Admin API. Its inputs are service and version identifiers, and its outputs are changes to the underlying database, including service version state and the runtime routes that direct traffic.

How it works

Service versions are managed as records in the s2r_service_version database table. Each version belongs to a single service and has a unique version number, a status (draft, active, archived), and a flag (is_active) indicating if it is the currently live version.

Creating a Draft Version

A new version is created as a draft by cloning an existing version. This allows API publishers to modify a service's configuration, operations, and mappings in isolation before making it live.

The process, executed by createDraftVersion, is as follows:

1. Source Version Resolution: The operation requires a source version to clone. If a sourceVersionId is not explicitly provided, the system automatically selects a source in the following order of preference:

   1. The currently active version of the service.
   2. If no version is active, the latest version by version_no. If no source can be found, the operation fails.

2. Pre-condition Check: The system verifies that the service does not already have a version with the status draft. A service can only have one draft at a time. If an existing draft is found, the operation fails.

3. Version Cloning: A new s2r_service_version record is created with a new UUID, the next available version_no, and its status set to draft.

4. Property Inheritance: The new draft inherits critical properties from the source version to ensure continuity and reduce reconfiguration. This includes:

   • The WSDL artifact link (wsdl_artifact_id), which is essential for certain service types.
   • All operations (s2r_operation records) are duplicated for the new version.
   • For each cloned operation, crucial configuration is carried over, including:
     • SOAP and REST binding details (soap_action, rest_method, rest_path).
     • Schema definitions (request_schema, response_schema, fault_schema).
     • WSDL binding style (binding_style) and SOAP headers (operation_headers).
     • Execution settings like timeout_ms, retry_count, and debug_enabled.
     • Asynchronous execution settings, including callback_path and callback_auth_mode.
   • The active transformation mapping (s2r_operation_mapping) for each operation is also cloned, ensuring that request and response transformations are preserved in the new draft.

The following diagram illustrates the draft creation flow:

flowchart TD
    subgraph Create Draft Version
        A[Start: serviceId, sourceVersionId?] --> B{sourceVersionId provided?};
        B -- Yes --> C[Verify sourceVersionId exists];
        B -- No --> D[Find active or latest version];
        C --> E[Set as sourceVersion];
        D --> E;
        E --> F[Check for existing draft];
        F -- Exists --> G[Fail: "draft version already exists"];
        F -- None --> H[Create new s2r_service_version row<br>(status='draft')];
        H --> I[Copy wsdl_artifact_id from source];
        I --> J[Query all operations from source version];
        J --> K{For each source operation};
        K -- Clone --> L[Create new operation row for draft version];
        L --> M[Copy properties: schemas, binding_style, headers, async settings, etc.];
        M --> N[Copy active transformation mapping];
        N --> K;
        K -- Done --> O[End: Return VersionDraftResult];
    end

Activating a Version

Activating a version makes it the single, live version for a service. This is an atomic operation that updates both the service's versioning state and the API Gateway's routing configuration. The activate and rollback functions both use this same underlying mechanism.

The activation process is as follows:

1. Deactivation: All existing versions for the service are marked as inactive (is_active = false). The previously active version has its status changed to archived.
2. Activation: The target version is marked as active (is_active = true) and its status is set to active. The parent service's status is also updated to active.
3. Route Purging: All existing runtime routes (s2r_runtime_route) for the service are deleted from the routing table.
4. Route Publishing: New routes are published for every enabled operation within the newly activated version.
   • Route Collision Guard: Before publishing, the system checks if any of the new routes conflict with existing routes owned by a different service. A conflict is defined by a unique combination of direction, environment, rest_method, and rest_path. If a collision is detected, the entire activation operation is rolled back to prevent one service from unintentionally "stealing" a route from another.
   • For each enabled operation, a record is inserted or updated in the s2r_runtime_route table, making the operation's endpoint live.

The following diagram illustrates the sequence of events during activation:

sequenceDiagram
    participant P as API Publisher
    participant A as Admin API
    participant L as Version Activation Logic
    participant DB as Platform Database

    P->>A: Activate Version(serviceId, versionId)
    A->>L: Start Activation
    L->>DB: Find current active version
    L->>DB: Deactivate all versions for service
    L->>DB: Activate target version (is_active=true, status='active')
    L->>DB: Delete existing runtime routes for service
    L->>DB: Get enabled operations for new version
    DB-->>L: Operation details
    L->>L: Check for route collisions with other services
    alt Collision Found
        L-->>A: Activation Failed (Error)
        A-->>P: Activation Failed
    else No Collision
        L->>DB: Publish new runtime routes
        DB-->>L: Routes published
        L-->>A: Activation Succeeded
        A-->>P: Activation Succeeded
    end

OpenAPI Import Association

A service version can be linked to a record of an OpenAPI import. This creates a clear line of provenance from the live service version back to the specific OpenAPI specification file that was used to define it.

The updateOpenapiImportId function updates this association.

• Providing a valid openapiImportId creates the link.
• Providing a null value clears any existing link.
• The operation will fail if the service version or the OpenAPI import record does not exist.

Programmatic API Reference

The component exposes several methods for managing service versions. These are typically not called directly by end-users but are foundational to the Admin API.

createDraftVersion

Creates a new draft version by cloning an existing version.

• Returns: VersionDraftResult containing the IDs and numbers of the new and source versions.
• Throws:
  • IllegalArgumentException: If the serviceId or sourceVersionId (if provided) is not found.
  • IllegalStateException: If a draft version already exists for the service.

activate

Activates a specific version of a service, making it the live version.

• Returns: VersionActivationResult containing details of the activation, including the previously active version ID.
• Throws: IllegalArgumentException if the service version is not found.

rollback

Rolls back to a previous version of a service. This is functionally identical to activate.

• Returns: VersionActivationResult with the action field set to "rollback".
• Throws: IllegalArgumentException if the service version is not found.

updateOpenapiImportId

Associates a service version with an OpenAPI import record.

• Returns: The updated VersionRecord.
• Throws:
  • IllegalArgumentException: If the service version is not found.
  • IllegalStateException: If the openapiImportId does not correspond to an existing import record.

findByServiceId

Retrieves all versions for a given service.

• Returns: A List<VersionRecord> ordered by version_no descending.

findById

Retrieves a single, specific version.

• Returns: An Optional<VersionRecord> which is empty if the version is not found.

Data Models

VersionRecord

Represents a single version of a service.

VersionDraftResult

The result of a createDraftVersion operation.

VersionActivationResult

The result of an activate or rollback operation.

Troubleshooting

All SOAP-to-REST docs