| title | description | author | ms.service | ms.custom | ms.topic | ms.date | ms.author |
|---|---|---|---|---|---|---|---|
Tutorial - Publish versions of your API using Azure API Management |
Follow the steps of this tutorial to learn how to publish multiple API versions in API Management. |
dlepow |
api-management |
mvc, devx-track-azurecli |
tutorial |
02/10/2021 |
danlep |
There are times when it's impractical to have all callers to your API use exactly 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 is possible to provided multiple versions in Azure API Management.
For background, see Versions & revisions.
In this tutorial, you learn how to:
[!div class="checklist"]
- Add a new version to an existing API
- Choose a version scheme
- Add the version to a product
- Browse the developer portal to see the version
:::image type="content" source="media/api-management-getstarted-publish-versions/azure-portal.png" alt-text="Version shown in Azure portal":::
- Learn the Azure API Management terminology.
- Complete the following quickstart: Create an Azure API Management instance.
- Also, complete the following tutorial: Import and publish your first API.
- In the Azure portal, navigate to your API Management instance.
- Select APIs.
- Select Demo Conference API from the API list.
- Select the context menu (...) next to Demo Conference API.
- Select Add version.
:::image type="content" source="media/api-management-getstarted-publish-versions/add-version-menu.png" alt-text="API context menu - add version":::
Tip
Versions can also be enabled when you create a new API. On the Add API screen, select Version this API?.
In Azure 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.
Enter the values from the following table. Then select Create to create your version.
:::image type="content" source="media/api-management-getstarted-publish-versions/add-version.png" alt-text="Add version window":::
| Setting | Value | Description |
|---|---|---|
| Name | demo-conference-api-v1 | Unique name in your API Management instance. Because a version is in fact a new API based off an API's revision, this setting is the new API's name. |
| Versioning scheme | Path | The way callers specify the API version. |
| Version identifer | v1 | Scheme-specific indicator of the version. For Path, the suffix for the API URL path. If Header or Query string is selected, enter an additional value: the name of the header or query string parameter. A usage example is displayed. |
| Products | Unlimited | 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 creating the version, it now appears underneath Demo Conference API in the API List. You now see two APIs: Original, and v1.
You can now edit and configure v1 as an API that is separate from Original. Changes to one version do not affect another.
Note
If you add a version to a non-versioned API, an Original is also automatically created. This version responds on the default URL. Creating an Original version ensures that any existing callers are not broken by the process of adding a version. If you create a new API with versions enabled at the start, an Original isn't created.
In order 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 add it to a product at any time.
For example, to add the version to the Unlimited product:
- In the Azure portal, navigate to your API Management instance.
- Select Products > Unlimited > APIs > + Add.
- Select Demo Conference API, version v1.
- Click Select.
:::image type="content" source="media/api-management-getstarted-publish-versions/08-add-multiple-versions-03-add-version-product.png" alt-text="Add version to product":::
When you create multiple versions, the Azure portal creates a version set, which represents a set of versions for a single logical API. Select the name of an API that has multiple versions. The Azure portal displays its Version set. You can customize the Name and Description of a virtual set.
You can interact directly with version sets by using the Azure CLI:
[!INCLUDE azure-cli-prepare-your-environment-no-header.md]
To see all your version sets, run the az apim api versionset list command:
az apim api versionset list --resource-group apim-hello-world-resource-group \
--service-name apim-hello-world --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 apim-hello-world-resource-group \
--service-name apim-hello-world --version-set-id 00000000000000000000000
For more information about version sets, see Versions in Azure API Management.
If you've tried the developer portal, you can see API versions there.
- Select Developer Portal from the top menu.
- Select APIs, and then select Demo Conference API.
- You should see a dropdown with 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.
In this tutorial, you learned how to:
[!div class="checklist"]
- Add a new version to an existing API
- Choose a version scheme
- Add the version to a product
- Browse the developer portal to see the version
Advance to the next tutorial:
[!div class="nextstepaction"] Customize the style of the Developer portal pages