Tutorial: Publish multiple versions of your API
APPLIES TO: All API Management tiers
There are times when it's impractical to have all callers to your API use the same version. When callers want to upgrade to a later version, they want an approach that's easy to understand. As shown in this tutorial, it's possible to provide multiple versions in Azure API Management.
For background, see Versions and Revisions.
Tip
API teams can use this feature in workspaces. Workspaces provide isolated administrative access to APIs and their own API runtime environments.
In this tutorial, you learn how to:
- Add a new version to an existing API
- Choose a version scheme
- Add the version to a product
- View the version in the developer portal
Prerequisites
- Learn Azure API Management terminology.
- Complete the quickstart Create an Azure API Management instance.
- Complete the tutorial Import and publish your first API.
Add a new version
- In the Azure portal, navigate to your API Management instance.
- In the left menu, in the APIs section, select APIs.
- Locate Swagger Petstore - OpenAPI 3.0 in the API list. Select the ellipsis (...) next to Swagger Petstore - OpenAPI 3.0 and then select Add version. You'll add values to the resulting window in the next section.
Tip
You can also enable versions when you create a new API. On the Add API screen, select Version this API?.
Choose a versioning scheme
In API Management, you choose how callers specify the API version by selecting a versioning scheme: Path, Header, or Query string. In the following example, Path is used as the versioning scheme.
In the Create a new API as a version window, enter the values from the following table. Then select Create to create your version.
| Setting | Value | Description |
|---|---|---|
| Version identifier | v1 | Scheme-specific indicator of the version. For Path, the suffix for the API URL path. |
| Versioning scheme | Path | The way callers specify the API version. If you select Header or Query string, enter another value: the name of the header or query string parameter. A usage example is displayed. |
| Full API version name | swagger-petstore-openapi-3-0-v1 | Unique name in your API Management instance. Because a version is actually a new API that's based on an API's revision, this value is the new API's name. |
| Products | Unlimited (provided in some service tiers) | Optionally, one or more products that the API version is associated with. To publish the API, you must associate it with a product. You can also add the version to a product later. |
After you create the version, it appears under Swagger Petstore - OpenAPI 3.0 in the API list. You now see two APIs: Original and v1:
Note
If you add a version to a non-versioned API, an original version is also automatically created. This version responds on the default URL. The original version ensures that calls from existing callers still work after the version is added. If you create a new API with versions enabled at the start, an original isn't created.
Edit a version
After you add the version, you can edit and configure it as an API that's separate from the original. Changes to one version don't affect another (for example, if you add or remove API operations, or edit the OpenAPI specification). For more information, see Edit an API.
Add the version to a product
For callers to see the new version, it must be added to a product. If you didn't already add the version to a product, you can do so at any time.
To add the version to a product:
- In the Azure portal, navigate to your API Management instance.
- Under APIs in the left pane, select Products.
- Select the product, and then select APIs in the left pane.
- Select + Add.
- Select the API.
- Click Select.
Use version sets
When you create multiple versions, the Azure portal creates a version set, which represents a set of versions for a single logical API. If you select the name of an API that has multiple versions, the portal displays its version set. You can customize the name and description of a version set.
You can interact directly with version sets by using the Azure CLI:
Use the Bash environment in Azure Cloud Shell. For more information, see Quickstart for Bash in Azure Cloud Shell.
If you prefer to run CLI reference commands locally, install the Azure CLI. If you're running on Windows or macOS, consider running Azure CLI in a Docker container. For more information, see How to run the Azure CLI in a Docker container.
If you're using a local installation, sign in to the Azure CLI by using the az login command. To finish the authentication process, follow the steps displayed in your terminal. For other sign-in options, see Sign in with the Azure CLI.
When you're prompted, install the Azure CLI extension on first use. For more information about extensions, see Use extensions with the Azure CLI.
Run az version to find the version and dependent libraries that are installed. To upgrade to the latest version, run az upgrade.
To see all your version sets, run the az apim api versionset list command:
az apim api versionset list --resource-group <resource-group-name> \
--service-name <API-Management-service-name> --output table
When the Azure portal creates a version set for you, it assigns an alphanumeric name, which appears in the Name column of the list. Use this name in other Azure CLI commands.
To see details about a version set, run the az apim api versionset show command:
az apim api versionset show --resource-group <resource-group-name> \
--service-name <API-Management-service-name> --version-set-id <ID from the Name column>
For more information about version sets, see Versions in Azure API Management.
View the version in the developer portal
If you use the developer portal, you can see API versions there.
- Select Developer portal at the top of the window.
- Select APIs, and then select Swagger Petstore.
- You should see a dropdown that lists multiple versions next to the API name.
- Select v1.
- Notice the Request URL of the first operation in the list. It shows that the API URL path includes v1.
Next step
Go to the next tutorial: