Revisions in Azure APIM are one of those concepts that I wish I had started learning from the beginning before I started doing anything within APIM.
It’s important to note that Revisions are different from Versions (which are a topic for another day).
When you start using APIM you’ll notice a little delineator in the top left corner as well as a tab that says “Revisions”, depending on what iteration you are on, a number will appear indicating the Revision Number.
If you ever want to toggle between your Revisions, you can select the drop-down arrow beside the date of the revision and select it from the list as indicated below.
What is a Revision?
As the name implies, revisions are checkpoints of work you have performed at x point in time. I like to think of them as changesets/commits that you might have committed to your repository. Each one can have its own description and you can toggle between the different revisions to test your changes.
When you start creating an API for the first time, the first revision is automatically created.
Accessing your Revisions
When you click on the Revisions tab, you will be presented with the list of revisions in place and their associated descriptions.
If you have never visited this tab and have solely been working on your API (as I have done many times), your initial description will be blank. This is where I think APIM should pop up on your first save of an API and prompt you for a description of what you are doing.
As indicated above, now that you have a revision in place, you can toggle between testing and validating old and new functionality. When all is tested and validated you can publish your revision, making your new work the current version that everyone else can see.
Publishing your Revision
Only 1 revision can ever be current and this is an important distinction between versions. Whereas your API can have multiple versions and revisions within them, you can only have 1 revision current per version.
To make a revision current, you right-click on the revision you want to make current, from the revisions tab check the box “Post to Public Change log for this API” and describe the change.
Upon completion of this change, I can not go to the Change log of my API and see the notes created herein.
Revisions are a great function that makes working with APIs while allowing for them to be online, possible as users can edit your current revision and you can keep testing in the safety of your environment the entire time.
It’s too bad my learning of revisions came after I had already completed some APIM projects as I could have used this early on.