Service Version Management Repository

Overview

The Version Repository is a data access component responsible for managing the lifecycle of API service versions. It provides a transactional and consistent interface for creating new draft versions of a service, activating a specific version to handle live traffic, and rolling back to a previous version.

This component interacts directly with the database to maintain the state of service versions, their associated operations, and the runtime routes they expose. It is a critical part of the service deployment process, ensuring that version changes are applied atomically and that runtime routing tables remain consistent and free of conflicts.

The repository is typically invoked by higher-level administrative services in response to an API publisher's actions to manage their service configurations. Its main functions are:

• Creating new, mutable "draft" versions by cloning an existing version.
• Activating a specific version, which makes it the live, public-facing version of the service.
• Publishing the necessary runtime routes for an activated version.
• Querying for existing service versions.

How it works

The repository manages two primary workflows: creating a draft version and activating a version.

Creating a Draft Version

A new version is always created as a draft by cloning an existing version. This allows API publishers to make changes to a service configuration without affecting the live, active version.

The process is as follows:

flowchart TD
    subgraph Create Draft Version
        A[API Publisher requests new draft] --> B{Resolve source version};
        B -- Explicit sourceVersionId --> C[Use specified version];
        B -- No sourceVersionId --> D{Find active version?};
        D -- Yes --> C;
        D -- No --> E[Find latest version by version number];
        E --> C;
        C --> F[Create new 'draft' version record in database];
        F --> G[Copy all operations from source version to new draft];
        G --> H[For each copied operation, copy its active mapping];
        H --> I[Return new draft version details];
    end

1. Resolve Source Version: The system first determines which version to clone. If a sourceVersionId is provided, that version is used. If not, the system attempts to find the currently active version for the service. If no version is active, it falls back to the latest version based on the version_no.
2. Create Version Record: A new record is inserted into the s2r_service_version table. It is assigned a new version_no (the previous maximum + 1), a new UUID, and its status is set to draft. The wsdl_artifact_id from the source version is also copied to the new draft.
3. Clone Operations: The system queries all operations from the source version and creates a new s2r_operation record for each one, associating it with the new draft version's ID. All properties are copied, including binding_style and operation_headers, to ensure functional parity.
4. Clone Mappings: For each newly created operation, the system finds the active s2r_operation_mapping from the corresponding source operation and copies it. This ensures that request and response transformations are carried over to the new draft.
5. Return Result: The process concludes by returning a VersionDraftResult containing the IDs of the new draft and the source version, along with a count of the operations that were copied.

This entire process is transactional. If any step fails, the entire operation is rolled back, and no new draft version is created.

Activating a Version

Activating a version makes it the live, immutable version of the service that handles runtime traffic. This is a critical, atomic operation that reconfigures the service's routing.

The activation process is as follows:

flowchart TD
    subgraph Activate Version
        A[API Publisher requests activation] --> B{Version exists?};
        B -- No --> X[Fail with error];
        B -- Yes --> C[Deactivate all existing versions for the service];
        C --> D[Set target version to 'active'];
        D --> E[Delete all runtime routes for the service];
        E --> F{Check for route collisions with other services};
        F -- Collision found --> X;
        F -- No collision --> G[Publish new routes for active version];
        G --> H[Return activation result];
    end

1. Deactivate Previous Versions: The system first deactivates all other versions of the service by setting their is_active flag to false. If a version was previously active, its status is changed to archived.
2. Activate Target Version: The target version's is_active flag is set to true and its status is set to active. The parent service's status is also updated to active.
3. Clear Existing Routes: All existing entries for the service in the s2r_runtime_route table are deleted. This ensures a clean state before publishing the new routes.
4. Route Collision Guard: Before inserting new routes, the system performs a critical safety check. It identifies all routes that the new version will create and verifies that none of them (a combination of HTTP method and path) are currently in use by a different service. If a collision is detected, the entire activation transaction is rolled back, and the activation fails.
5. Publish New Routes: For every enabled operation in the newly activated version, a new record is inserted into the s2r_runtime_route table. This table is used by the gateway to direct incoming requests to the correct service operation. This step uses an upsert (insert on conflict update) operation, which allows a service to reclaim a route it already owns but prevents it from taking a route from another service, as enforced by the collision guard.
6. Return Result: The process returns a VersionActivationResult, which includes the ID of the newly activated version and the ID of the version that was previously active.

The rollback method is functionally identical to activate. It uses the same internal logic to activate a specified version, which is typically a previously active one.

Data Structures

VersionRecord

The VersionRecord represents a single version of a service. It is returned by findByServiceId and findById.

API Reference

The VersionRepository exposes the following public methods for managing service versions.

createDraftVersion

Creates a new draft version by cloning an existing version.

VersionDraftResult createDraftVersion(UUID serviceId, UUID sourceVersionId, String actor)

Parameters

Returns

A VersionDraftResult object containing the serviceId, the newVersionId of the draft, the new version_no, the sourceVersionId that was cloned, and a count of the operations copied.

activate

Activates a specific service version, making it the live version. This deactivates any previously active version and republishes the service's runtime routes.

VersionActivationResult activate(UUID serviceId, UUID versionId, String actor)

Parameters

Returns

A VersionActivationResult object containing the serviceId, the activatedVersionId, the previousActiveVersionId (if any), the number of routes published, and the action performed ("activate").

rollback

Rolls back to a previous service version by activating it. This is an alias for the activate method but is semantically used for activating an older version.

VersionActivationResult rollback(UUID serviceId, UUID versionId, String actor)

Parameters

Returns

A VersionActivationResult object. The action field in the result will be "rollback".

updateOpenapiImportId

Associates a service version with a record from an OpenAPI import process.

VersionRecord updateOpenapiImportId(UUID serviceId, UUID versionId, UUID openapiImportId)

Parameters

Returns

The updated VersionRecord for the service version.

findByServiceId

Finds all versions for a given service, ordered by version number descending.

List<VersionRecord> findByServiceId(UUID serviceId)

Parameters

Returns

A List of VersionRecord objects. Returns an empty list if the service has no versions.

findById

Finds a specific service version by its ID.

java.util.Optional<VersionRecord> findById(UUID serviceId, UUID versionId)

Parameters

Returns

An Optional containing the VersionRecord if found, or an empty Optional if not.

Troubleshooting

When interacting with the VersionRepository, the following exceptions may be thrown, indicating specific error conditions.

All SOAP-to-REST docs