Events
Mar 17, 11 PM - Mar 21, 11 PM
Join the meetup series to build scalable AI solutions based on real-world use cases with fellow developers and experts.
Register nowThis browser is no longer supported.
Upgrade to Microsoft Edge to take advantage of the latest features, security updates, and technical support.
APPLIES TO: All API Management tiers
When your API is ready to go and is used by developers, you eventually need to make changes to that API and at the same time not disrupt 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 so you can model and test changes safely. When ready, you can make a revision current and replace your current API.
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:
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 another 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 is used for.
Select Create.
Your new revision is now created.
Note
Your original API remains in Revision 1. This is the revision your users continue to call, until you choose to make a different revision current.
Select Swagger Petstore from the API list.
Select the Design tab near the top of the screen.
Notice that the revision selector (directly 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.
Select the Revisions tab from the menu near the top of the page.
Open the context menu (...) for Revision 2.
Select Make current.
Select the Post to Public Change log for this API checkbox, if you want to post notes about this change. Provide a description for your change that the developers can see, for example: Testing revisions. Added new "test" operation.
Revision 2 is now current.
If you've tried the developer portal, you can review the API changes and change log there.
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.
In this tutorial, you learned how to:
Advance to the next tutorial:
Events
Mar 17, 11 PM - Mar 21, 11 PM
Join the meetup series to build scalable AI solutions based on real-world use cases with fellow developers and experts.
Register nowTraining
Module
Publish and manage your APIs with Azure API Management - Training
Learn about using an Azure API gateway to share APIs with partners, and how to use subscription keys to control access to your APIs.
Certification
Microsoft Certified: Azure Cosmos DB Developer Specialty - Certifications
Write efficient queries, create indexing policies, manage, and provision resources in the SQL API and SDK with Microsoft Azure Cosmos DB.