Version
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.
Add a new version
- 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.
Test the new version
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
v2
version of the Star Wars API. -
Notice the request URL and the inclusion of
v2
in the path. -
Test the
GetPeople
operation.
What Versions Enable
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.