Today we are excited to announce the public preview of support for Versions and Revisions in Azure API Management! This new feature gives you flexibility and control in how you manage change and the lifecycle of your API.
What are Versions & Revisions?
It helps to first explain what we mean by these terms – as they are two distinct, yet related, features:
- Versions allow you to present groups of related APIs to your developers. Versions differentiate themselves through a version number (which is a string of any value you choose), and a versioning scheme (path, query string or header).
- Revisions allow you to make changes to your APIs in a controlled and safe way. When you want to make changes, create a new revision. You can then edit and test API without disturbing your API consumers. When you are ready, you can then make your revision current – at the same time, you can post an entry to the new change log, to keep your API consumers up to date with what has changed.
So what can I do with these new features?
With revisions you can:
- Safely make changes to your API Management API definitions & policies, without disturbing your production API.
- Try out changes before publishing them.
- Document the changes you make, so your developers can understand what is new.
- Rollback if you find issues.
With versions you can:
- Publish multiple versions of your API at the same time
- Use path/query string or header to differentiate between versions.
- Use any string value you wish to identify your version (a number, a date, a name).
- Show your API versions grouped together on the developer portal.
You should be able to find the versions and revisions feature in the context menu of the APIs screen in the new Azure Portal.
FAQ
Q. Do I have to use Versions & Revisions?
A. No! Existing customers can carry on using API Management just as they did before. The only difference they will find is that each API will now have one revision (which should not effect the operation of their API in any way).
Q. Do I have to use Versions & Revisions together?
A. No! You can use Versions and not use revisions, you can use revisions and not versions.
Q. How are Versions & Revisions related?
A. Each version can have multiple revisions, just like a non-versioned API. Should you find that your revision has breaking changes, or if you wish to formally turn your revision into a beta/test version, you can select ‘Create Version from Revision’ on the revision context menu on the Revisions tab.
Q. I’m creating a new API. Should I enable Versions from the start?
A. It depends on the use case for your API, there is no downside to doing so.
Q. Can I use Revisions to roll back changes in case of failure/errors?
A. Yes!
Q. Do revisions replace source control or CI/CD systems?
A. No. Revisions are an extra layer of control. If you use CI/CD systems, GIT, VSTS, ARM etc. with your API Management service you should continue to do so.
Q. Are revision private URLs visible to my developers?
A. Whilst a revision’s private URL requires the caller knows the revision number to form up the call, the private address of the revision otherwise has the same security context as the current revision (unless of course you have deliberately changed it in that revision e.g. making a policy change). We would suggest disabling the private revision URL when not in use for testing.
To help you understand and get started, take a look a the following:
- Understand API versioning with our very own Darrel Miller; and how we decided to build this feature the way we did.
- Get started with revisions.
- Get started with versions.
- See how this feature works end-to-end in our video below.