Versioning of API (definitions)

One of the significant benefits of centrally managing back-end services with Azure API Management is versioning. With versioning, you can publish your API (definitions) multiple time with a different set of operations, use a different path, query-string, or header specifications for your operations, and create a new version of a non-versioned API without breaking changes. Versioning brings a lot of flexibility for gateway possibilities to your back-end services.

When creating an API (definition), you can choose to version from the start. At the bottom of the API definition screen in the Azure Portal, you will see the option ‘Version this API?’. When checking this option, a few details will appear, such as the versioning scheme. Note that there are several versioning schemes possible:

• Path-based versioning
• Header-based versioning
• Query string-based versioning

And next to scheme options you need to set the version identifier, which can be any string value you choose.
As mentioned earlier, you can version APIs that do not have a version. In the Azure Portal, you click … next to the API (definition) and choose Add version.

What will next is that a new version set will be created, the existing version is maintained and configured as the Original API version, and a new version is created as a new API and is linked to the version set.
When defining your API (definitions) as gateways for your back-end services, it is best to start applying version from the start.