Map your systems
Versions and releases
Run API versions side by side, read the history and diff of every endpoint, create releases with a suggested version, and check old copies.
Open Systems in the appTwo kinds of version
API versions
The API version is part of how contracts are matched, so /login in v1 and /login in v2 are two different endpoints. A consumer of v1 is only matched with v1. It is taken from the path (/api/v2/…) unless you set API version in the editor.
The APIs tab groups endpoints by version, with how many systems consume each one. On the Releases page, with the system picked, API versions & adoption shows every version with its consumers, so you can see who still needs v1 before you deprecate it.
To start a new version:
- Open the provider's APIs tab. Its endpoints are grouped by version.
- On the version to start from, press Copy to new version. A system without endpoints has nothing to copy yet: add one first.
- Check From and type the New version, such as
v3. - Press the create button. Every endpoint is copied into the new version as a To do, so you can change it without touching the old one.
The Releases page links to the APIs tab for this.
To give one endpoint a new version, and leave the rest where they are:
- On the APIs tab, press New version on the endpoint's row.
- Type the New version, such as
v2. It can be a new version or one the system already has, as long as that version doesn't have this endpoint yet. - Press the copy button. The endpoint is copied into that version as a To do, with its path moved to it (
/api/v1/ordersbecomes/api/v2/orders).
New version works only for an endpoint that runs in Production: the release deployed there has it, and it isn't a to-do. Until then its button shows a lock, and pressing it says why.
When a release that brings a newer version of an endpoint is deployed to Production, the older versions of that endpoint are deprecated on their own, with the new one as their replacement. See Deprecations.
When a provider has a newer version of a path, an unresolved consumer gets the suggestion "Available in" that version.
Endpoint history
Every save of an endpoint is a revision. Open the endpoint and its History tab.
- Pick a revision on the left. It shows who saved it, when, and how many changes were breaking or additive.
- The right side shows each change: added, removed or changed, marked breaking, additive or neither. Under it, "Breaking for" names the consumers that read what was removed.
- Press Restore to make that revision the newest one. History is never rewritten.
Moving an endpoint's lifecycle or deprecating it doesn't make a revision. Who did it, and when, is listed under Lifecycle and deprecation on the current revision.
The History tab of a contract shows how that contract changed over time.
Releases
A release saves a system's endpoints and logic as they are published to Development at a version (no one's unpublished changes), so you can record where it runs and check it is safe to deploy.
- Open Releases in the sidebar, pick the system, and press New release. (With All systems picked, New release asks which system.)
- Read the Suggested version. It counts the changes since the last release that break callers, the new things and the other changes, and names the kind of release: Big change, Addition or Fix.
- Keep the suggestion or type another Version.
- Optionally write Notes: what changed, for whoever deploys it.
- Press Create release.
When the release breaks calls that the last release didn't, it asks first, for example "Breaks 1 caller once deployed?", with each call and why. This happens even while the endpoint is still To do or In progress. If the version you typed keeps the first number, such as 1.1.0 after 1.0.0, it also says that callers will read it as a safe update. Press Create anyway to make it. Publishing your changes asks the same way, with Publish anyway.
To change a release's notes later, open the release in the list and press Edit notes (or Add notes). Its version and what it holds stay as they were.
Releases lists each release with its code version, endpoints, logic, where it is deployed and when it was made. Click a row to see what changed since the release before it. With two or more releases, Compare shows the difference between any two. You make releases here; your CI then checks them and records where they're deployed. See CI and the API and Environments and deployments.
Named versions
Logic, flows, test data and expected results are saved as revisions too. To give one a version people can refer to, press Save version in its versions panel. The first is 1.0.0, and a version number is suggested from what changed. You can compare any version with now and restore it. See Logic and Test data and expected results.
Everything versioned under a system
Below the releases, Everything versioned lists where each object of the system stands now: releases, logic, flows, test data, expected results and exports.
- What changed between compares two releases, or a release and Now (unreleased): endpoints, logic, flows, test data and expected results that moved, and what was exported in between.
- Check my copy answers "is my copy current?". Paste the first line of a generated file, a whole file, its hash, exported text steps or an exported OpenAPI document, and press Check. It says which version it came from, whether it was edited, and what changed since.
Related
- Retiring APIsRetire an API with a shutdown date and a replacement, and follow every consumer until they have all moved off.
- Import and exportBring in OpenAPI, Postman, Pact and browser recording (HAR) files, sync again when they change, and export OpenAPI and Pact.
- Environments and deploymentsRecord which release of each system runs in each environment, see compatibility per environment, and check a release before you deploy it.
- CI and the APIGate deployments in CI with the safety check and record what you deploy, using an API token and the HTTP API.
- Code generationSee the code for a logic as you build it, take it away as files, and check it returns what the test cases returned.
