RabbinatixDocs
Sign inGet started

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 app

Two kinds of version

KindExampleWhat it is
API versionv1, v2A version of the API itself. Several can run side by side.
Release2.4.0A snapshot of a system at one moment, for deployments

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:

  1. Open the provider's APIs tab. Its endpoints are grouped by version.
  2. On the version to start from, press Copy to new version. A system without endpoints has nothing to copy yet: add one first.
  3. Check From and type the New version, such as v3.
  4. 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:

  1. On the APIs tab, press New version on the endpoint's row.
  2. 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.
  3. Press the copy button. The endpoint is copied into that version as a To do, with its path moved to it (/api/v1/orders becomes /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.

  1. Pick a revision on the left. It shows who saved it, when, and how many changes were breaking or additive.
  2. 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.
  3. 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.

  1. Open Releases in the sidebar, pick the system, and press New release. (With All systems picked, New release asks which system.)
  2. 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.
  3. Keep the suggestion or type another Version.
  4. Optionally write Notes: what changed, for whoever deploys it.
  5. 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.

Changes since the last releaseSuggested version
Anything that breaks callersBig change: 2.4.0 → 3.0.0
Only new thingsAddition: 2.4.0 → 2.5.0
Anything elseFix: 2.4.0 → 2.4.1

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.
TipGenerated code and OpenAPI exports carry their version and a hash, so you can always trace a copy back. See Code generation and Import and export.