API Platform Versioning Policy

Learn about the four independent versioning surfaces in the API platform—product releases, database schemas, service mappings, and generated contracts.

Overview

The API platform uses four independent but coordinated versioning surfaces. Understanding how each surface is versioned is essential for safe upgrades and for reasoning about what a specific version number signifies in different contexts. The four versioning systems are:

Product Version: A release of the entire platform, including all software components and documentation.
Database Schema Version: The version of the underlying PostgreSQL database schema, managed by automated migrations.
Per-Service Mapping Version: An immutable, versioned snapshot of a single service's SOAP-to-REST mapping configuration.
Generated-Contract Version: The version of the consumer-facing OpenAPI or WSDL artifact generated from a specific service mapping version.

These versioning schemes are deliberately decoupled. This design allows you to upgrade the core platform without being forced to republish every service, and conversely, to update an individual service's mapping without needing to upgrade the entire platform.

How the Versions Relate

A top-level product release pins a specific database schema version and includes the container images that run the platform. These running services, in turn, serve the specific mapping versions that you, the API publisher, choose to activate for each service.

flowchart TD
    A[Product Release <br/> e.g., v2.1.0] -->|pins| B(Database Schema Version <br/> Flyway V&lt;n&gt;);
    A -->|runs| C(Platform Images <br/> Control Plane, Runtime, Worker);
    C -->|serves| D{Per-Service Mapping Versions};
    D -->|generates| E(Generated Contract <br/> OpenAPI v3 / WSDL);

    subgraph "Managed by Platform"
        A
        B
        C
    end

    subgraph "Managed by API Publisher"
        D
        E
    end

Key relationships to understand are:

Upgrading the product version may advance the required database schema version, but it does not automatically change the active mapping version for any of your services.
Activating a new mapping version for a service changes only that service's behavior; it does not affect the underlying product or database schema versions.

Product Version

The product version (e.g., v1.0, v1.1, v2.0) identifies a complete release of the platform. This includes the container images for the control plane, runtime, and worker components, as well as the documentation set and associated deployment artifacts.

The version format is vMAJOR.MINOR.PATCH:

MAJOR: Indicates a significant shift in capability or a breaking change to a public API. It may also signal a change to the license contract.
MINOR: Indicates new capabilities added in a backward-compatible manner.
PATCH: Indicates backward-compatible bug fixes only.

Each deployment is stamped with build provenance metadata, including the commit SHA, branch, build timestamp, and image tag. This information is emitted in a log line at startup, allowing an operator to confirm the exact build that is running. Release notes are published for each product version.

Database Schema Version

The platform's PostgreSQL database schema is managed using Flyway migrations. These migrations are applied automatically when the platform services start up.

Immutable Migrations: Each migration is an immutable, numbered SQL script with the format V<n>__description.sql. Once a migration script is shipped in a release, it is never edited. Any necessary corrections are handled by a new, subsequent migration script.
Automatic Application: You do not manage these migrations manually; they are included with each product release and applied on startup.
Startup Validation: Before serving traffic, services validate that the connected database schema is at, or compatible with, the version expected by the running software.
No-Stall Upgrades: Migrations that involve building indexes on large tables are handled out-of-band to ensure that a platform upgrade does not stall on a long-running database operation.

For the operational sequence during an upgrade, see the platform upgrade guide.

Per-Service Mapping Version

The SOAP-to-REST mapping for each individual service is independently versioned. This is the versioning surface most relevant to the day-to-day operations of an API publisher.

Immutability: Every change to a service's mapping or its generated contract creates a new, immutable version. Existing mapping versions are never modified.
Activation and Rollback: At any given time, exactly one mapping version is active for a service. You can activate any existing version to make it live, or instantly roll back to a previous version.
Consumer Contract Stability: Because mapping versions are immutable, API consumers are protected from silent, unexpected changes to the service contract. A contract change is always a new version that you must deliberately activate.
Deterministic Regeneration: Each mapping version snapshot records the parser version and a content checksum. This ensures that regenerating a contract from a given mapping version is a deterministic process. It also means that a change in a backend WSDL will surface as a clear diff against the previous version.

For more details, see the guide on publishing and versioning a service.

Generated-Contract Version

The final artifacts you provide to API consumers—an OpenAPI v3 document (for published REST APIs) or a WSDL file (for consumed SOAP services)—are generated from the active mapping version of a service.

Regenerating a contract from a specific mapping version is a deterministic operation. If you need to introduce a breaking change for your API consumers, the recommended practice is to create and publish a new service mapping version. If you version your public API paths, you can expose this new version under a new path (e.g., /v2/myservice) rather than mutating the live contract at its existing path.

License Compatibility

The license contract is tied to the MAJOR line of the product version. A product upgrade to a new MAJOR version may require a new license file that corresponds to the new license format version. Any upgrade that requires a license change will be explicitly noted in the corresponding release notes. The license model documentation describes the contract in detail.