Versioning
API Hub for Design allows you to manage multiple versions of your API or domain definitions. You typically start a new version when you need to add new API operations or parameters, add data models, and so on. Once a new version is ready to be consumed by client applications, you can publish it. This way, you can continually enhance your APIs while having a clean, published version for your API consumers.
Version list
All the versions are listed in the dropdown next to the API (domain) name, so you can switch between the versions with just a few clicks.
The API version is also stored in the info.version
key in the API definition:
info: title: Petstore version: 1.0.0
API versions do not depend on each other. They can have different API operations, parameters, descriptions, and so on. The following things are version-specific and are not shared between the versions:
the contents of the API definition,
the public/private and published/unpublished status,
integrations (but you can carry over some integrations when you create a new version),
Version format
Usually, version numbers look like 1.0.0, but they can actually include any of these characters:
0-9 A-Z a-z . _ - +
Note: A version number must start and end with a digit or letter. The plus (+) character in versions is currently supported in API Hub for Design SaaS only.
Below are examples of valid version numbers:
1 1.0 0.0.1 1.2.3.4 2.4_15 1.0b5 1.2.0-rc3 v1 beta 2016-04-15 2.0.0-SNAPSHOT+20211116
You can choose any versioning scheme, but we recommend semantic versioning, which uses three-part version numbers in the format major.minor.patch
.
Add a new version
Anyone with edit access to the API can create and delete versions. This includes the API owner and designers
There are several ways to add a new version to an API or domain.
Note
When you create a new API version, you can also carry over some existing integrations to the new version.
Option 1
Open the dropdown next to the version number, select Add New Version, then enter a new version number. The new version will contain the same content as the current one.
Option 2
You can change the version
in the info
section of your API or domain. If you do this, the Save button will change to Create New Version. Click it to save the content as a new version.
Note: This works only for unpublished APIs and domains, because published APIs are read-only and cannot be edited.
Version sorting
If an API or domain uses semantic versioning (major.minor.patch
), API Hub for Design Editor displays the versions in descending order, with the latest version on top. Version numbers in other formats are displayed in the order they were created.
Set the default version
The default version is what is shown in search results in API Hub for Design or when someone navigates to your API or domain definition directly without a specific version number, such as https://app.swaggerhub.com/api/swagger-hub/registry-api/. In the editor, the default version is marked with the icon.
To change the default version, click Set as default next to that version:
Additionally, when you create a new version or publish a version, you can set this version as the default one:
See who created a version
You can see who created an API or domain version at the bottom of the Info panel:
Note: The Created By information is only available for the API and domain versions that were:
created in API Hub for Design SaaS after November 26, 2019,
created in API Hub for Design On-Premise 1.23 and later.
Information about earlier versions can be found in historical audit logs.
Rename a version
There is no direct way to rename versions, but you can use the following workaround:
Switch to the version you want to rename.
Create a new version with the desired version number.
Delete the old version.
Compare versions
You can compare two API versions to see how they differ. To do that:
Open your API and select one of the versions you want to compare.
In the version list, click next to the version to compare with.
This will open the diff view where you can see the differences between the versions.
You can also compare versions of different APIs, as explained in Comparing and Merging API Versions.
Delete a version
If your API has two or more versions, you can delete the old versions you no longer need. This action cannot be undone. Note that if the API has only one version, you can delete the API instead.
Note
You can delete only unpublished versions. If a version is published, you must unpublish it first: select this version, click .
To delete a version, click next to that version in the version list.