Proper version management not only helps organize your API, it also aids in Azure API Management. In this exercise we are going to version an existing API.
Good practice: Integrate version management from the beginning with a v1 or similar identifier.
- Select the Star Wars API.
- Click on the ellipsis and select Add version.
- Add a new version with these values, then press Create:
- Version identifier: v2
- Versioning scheme: Path
- Full API version name: star-wars-v2
This name must be unique across the Azure API Management instance. Therefore, a combination of the API name and its version identifier is both semantic and suitable.
Products: Starter and Unlimited
- The new version, v2, is now added in the Star Wars API.
Any previous implementation of the newly-versioned API will simply be set to Original. This is a purely organizational change within APIM. The version continues to operate on the same previous URL without a version identifier - there is no impact to the consumers.
Sometimes, the version creation takes just a little bit of time. If you do not see it immediately, please keep refreshing and ensure you select the appropriate version as per below instructions.
In the Developer Portal select the
v2version of the Star Wars API.
Notice the request URL and the inclusion of
v2in the path.
Now that you have created a new version of the API, you have the ability to introduce breaking changes. Often times a breaking change in a backend API necessitates an API version change in APIM. Leaving a legacy implementation behind to focus on more contemporary API implementations also is a common versioning use case. Whatever the reason may be, Azure API Management provides means to abstract breaking changes in a responsible and safe manner.