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

      APIM Versions Add APIM Version Create

    • 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.

      APIM Version Created

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.

    APIM Developer Portal Versions

  • Notice the request URL and the inclusion of v2 in the path.

    APIM Developer Portal Version 2

  • Test the GetPeople operation.

    APIM Developer Portal Test Version

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.