Tutorial: Use revisions to make nonbreaking API changes safely

APPLIES TO: All API Management tiers

When your API is used by developers, you eventually need to make changes to that API without disrupting callers of your API. It's also useful to let developers know about the changes you made.

In Azure API Management, use revisions to make nonbreaking API changes. You can model and test changes safely. When ready, make your revision current and replace the current API.

For more information, 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 revision
Make nonbreaking changes to your revision
Make your revision current and add a change log entry
Browse the developer portal to see changes and change log
Access an API revision

Prerequisites

Learn the Azure API Management terminology.
Complete the following quickstart: Create an Azure API Management instance.
Complete the following tutorial: Import and publish your first API.

Add a new revision

Sign in to the Azure portal, and go to your API Management instance.
In the left menu, under APIs, select APIs.
Select Swagger Petstore from the API list, or a different API to which you want to add revisions.
Select the Revisions tab.
Select + Add revision.

Tip

You can also select Add revision in the context menu (...) of the API.
Provide a description for your new revision, to help remember what it's used for.
Select Create.

Your new revision is now created.

Note

Your original API remains in Revision 1. This one is the revision your users continue to call, until you choose to make a different revision current.

Make nonbreaking changes to your revision

Select Swagger Petstore from the API list.
Select Design near the top of the screen.

The revision selector above the design tab shows Revision 2 as currently selected.

Tip

Use the revision selector to switch between revisions that you wish to work on.
Select + Add Operation.
Set your new operation to POST, and the Display name, Name, and URL of the operation as test.
Save your new operation.

You've now made a change to Revision 2.
Use the revision selector near the top of the page to switch back to Revision 1.

Notice that your new operation doesn't appear in Revision 1.

Make your revision current and add a change log entry

Portal
Azure CLI

From the menu near the top of the page, select Revisions.
Open the context menu (...) for Revision 2.
Select Make current.
If you want to post notes about this change, select Post to Public Change log for this API. Provide a description for your change that the developers can see, for example: Testing revisions. Added new "test" operation.

Revision 2 is now current.

To begin using Azure CLI:

Use the Bash environment in Azure Cloud Shell. For more information, see Get started with 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 Authenticate to Azure using Azure CLI.
- When you're prompted, install the Azure CLI extension on first use. For more information about extensions, see Use and manage 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.

Use this procedure to create and update a release.

Run the az api list command to see your API IDs:
```
az apim api list --resource-group apim-hello-word-resource-group \
    --service-name apim-hello-world --output table
```
The API ID to use in the next command is the Name value. The API revision is in the ApiRevision column.

To create the release, with a release note, run the az apim api release create command:

az apim api release create --resource-group apim-hello-word-resource-group \
    --api-id swagger-petstore --api-revision 2 --service-name apim-hello-world \
    --notes 'Testing revisions. Added new "test" operation.'

The revision that you release becomes the current revision.

To see your releases, use the az apim api release list command:
```
az apim api release list --resource-group apim-hello-word-resource-group \
    --api-id swagger-petstore --service-name apim-hello-world --output table
```
The notes you specify appear in the change log. You can see them in the output of the previous command.

When you create a release, the --notes parameter is optional. You can add or change the notes later using the az apim api release update command:

az apim api release update --resource-group apim-hello-word-resource-group \
    --api-id swagger-petstore --release-id 00000000000000000000000000000000 \
    --service-name apim-hello-world --notes "Revised notes."

Use the value in the Name column for the release ID.

You can remove any release by running the az apim api release delete command:

az apim api release delete --resource-group apim-hello-word-resource-group \
    --api-id swagger-petstore --release-id 00000000000000000000000000000000 
    --service-name apim-hello-world

Browse the developer portal to see changes and change log

If you try the developer portal, you can review the API changes and change log there.

In the Azure portal, navigate to your API Management instance.
In the left menu, under APIs, select APIs.
Select Developer portal from the top menu.
In the developer portal, select APIs, and then select Swagger Petstore.
Notice your new test operation is now available.
Select Change log near the API name.
Notice that your change log entry appears in the list.

Access an API revision

Each revision to your API can be accessed using a specially formed URL. Add ;rev={revisionNumber} at the end of your API URL path, but before the query string, to access a specific revision of that API. For example, you might use a URL similar to the following to access revision 2 of the Swagger Petstore API:

https://apim-hello-world.azure-api.net/store/pet/1;rev=2/

You can find the URL paths for your API's revisions on the Revisions tab in the Azure portal.

Tip

You can access the current revision of your API using the API path without the ;rev string, in addition to the full URL that appends ;rev={revisionNumber} to your API path.

Summary

In this tutorial, you learned how to:

Add a new revision
Make nonbreaking changes to your revision
Make your revision current and add a change log entry
Browse the developer portal to see changes and change log
Access an API revision

Next step

Advance to the next tutorial:

Publish multiple versions of your API

Feedback

Was this page helpful?

Last updated on 2026-02-06