Tracking API Swagger Version Bumps Across Environments¶

Applications release new versions of their APIs, and those releases move through the environments of the release pipeline one at a time: DEV first, then IST, QA, UAT and finally PROD. For a while, different environments run different versions of the same API.

BizMetry follows those releases with versions of the API Collection, versions of the template linked to them, and the Business Events built on each template version. This page explains how to take a Swagger change from the application all the way to the Business Events of each environment.

The Model in Short¶

• Every change to a published Swagger contract produces a new version of the API Collection.
• Every template version is linked to one version of each API Collection it uses (see API Collections and Lifecycle Management).
• Every environment is assigned one template version.

So each environment uses exactly the contract its application exposes:

flowchart LR
    subgraph DEV
      D["Template v1.6"] --> DA["Agent Management API v2.1.0"]
    end
    subgraph QA
      Q["Template v1.5"] --> QA2["Agent Management API v2.0.0"]
    end
    subgraph PROD
      P["Template v1.5"] --> PA["Agent Management API v2.0.0"]
    end

Step 1 — Update the API Collection¶

When the application's contract changes, update its API Collection: open the collection version currently in use and bring in the new contract, from a file, from an agent, or by editing it in the Swagger editor. See Editing an Existing API Collection.

Because that version is PUBLISHED, BizMetry leaves it untouched and creates a new version in DRAFT with the new contract: a major version bump (for example v2.0.0 → v3.0.0) if the contract has breaking changes, a minor one (v2.0.0 → v2.1.0) otherwise. See Version Bump Mechanism. Business Events using the published version are not affected.

Step 2 — Publish the New Collection Version¶

Take the new collection version through its review flow until it's PUBLISHED. See Collection Lifecycle.

Step 3 — Fork the Template¶

Edit the template version currently assigned to the environment where the new application release will run. Because it's published, saving any change creates a new child template version in Draft.

In the API Collections tab, switch the collection's Version drop-down to the new collection version, and save. Make any other model changes the new release needs, then publish the new template version.

Step 4 — Assign the Template to the Environment¶

Assign the new template version to the environment that received the new application release, for example DEV. See Template Assignment Rules.

The other environments keep their current template version and keep capturing with the previous contract.

Step 5 — Move the Business Events¶

When the environment moves to the new template version, BizMetry forks the published Business Events of the previous template version into new DRAFT versions on the new template version. See Automatic Fork-on-Bump.

Each new DRAFT is then moved to the API Collection versions linked to the new template version automatically:

• Its operations are switched to the new collection version.
• Its mappings are reviewed against the changes between the two contract versions, as described in Recomputed Business Events: mappings that read removed fields are dropped, and IntelliSense tries to remap them.
• The version shows the Recomputed badge. Its tooltip lists the collection versions it moved between and anything dropped, remapped or needing review.

Review each new DRAFT, complete any mapping IntelliSense couldn't fill in the edit wizard or the Biz Event Composer, and then publish the Business Event version.

Step 6 — Promote Through the Pipeline¶

When the new application release reaches the next environment (IST, QA, UAT, PROD), assign the same template version to it. Its Business Events are already published for that template version, so the environment starts capturing with the new contract right away.

Once no environment uses the old template version, you can retire it, and then retire the old collection version.

Related Topics¶

• API Collections and Lifecycle Management
• API Collections Tab
• Biz Event Lifecycle Management
• Versioning & Fork-on-Bump
• API Collections — Overview & Lifecycle