Skip to main content Link Menu Expand (external link) Document Search Copy Copied


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.