API Versioning in Azure API Management

1. The "Why" of API Versioning

As a developer, you know that evolving an application's interface can be tricky. The same applies to REST APIs. A breaking change is any modification to your API that could cause existing client applications to fail. Common examples include:

• Changing the data format of a response (e.g., from an integer to a string).
• Renaming or removing a field in the JSON payload.
• Removing an API endpoint or operation.
• Changing an authentication mechanism.

Introducing such changes to a live API without a versioning strategy would be disruptive. API versioning allows you to publish multiple versions of your API simultaneously, giving clients the time to migrate to the new version at their own pace.

To understand the core concepts, let's start with a foundational resource from Microsoft.

2. Versioning Schemes in API Management

APIM provides three standard methods, or "schemes," to let a client specify which version of an API it wants to call.

Let's explore these schemes.

To summarize the three schemes:

1. Path-based: The version identifier is part of the URL path. This is very explicit and a common best practice.
   Example: https://my-apim.azure-api.net/api/v2/weatherforecast

2. Header-based: The version is specified in a custom HTTP request header.
   Example: GET /api/weatherforecast with header Api-Version: v2

3. Query string-based: The version is passed as a query parameter in the URL.
   Example: https://my-apim.azure-api.net/api/weatherforecast?api-version=v2

The path-based approach is often favored because it makes the resource URLs unique and unambiguous.

While we will use path-based versioning in our hands-on exercise, it's good to see what the configuration for another scheme looks like in the portal.

3. A Critical Distinction: Versions vs. Revisions

Before we implement versioning, it's essential to understand the difference between Versions and Revisions in APIM. This is a common point of confusion and a likely topic for the AZ-204 exam.

Here's a summary to help solidify the concepts:

In short: use versions to evolve your API contract, and use revisions to safely update the implementation of a specific version.

4. Hands-On: Publishing a New API Version

Now, let's apply this knowledge by creating a v2 of the API you have been working with in this module. We will use the path-based versioning scheme.

This walkthrough will guide you through the process, which is a core skill for the exam.

Let's walk through the key steps from the tutorial together:

1. Add a New Version

• In the Azure portal, navigate to your APIM instance and select APIs.
• Find your API (e.g., the WeatherForecast API). Click the ellipsis (...) and select + Add version.

2. Configure the Version

• In the "Create a new API as a version" dialog:
  • Versioning scheme: Select Path.
  • Version identifier: Enter v2. This will be the segment in your URL (e.g., /v2).
  • Products: Ensure your Unlimited product (or another product) is selected.
• Click Create.

3. Observe the Result: Version Sets and the 'Original' Version

• Back in the API list, you'll see your API is now a collapsible group called a Version Set.
• Inside, you will find two APIs:
  • Original: This is your initial API. It remains available at the original URL (without a version path) to ensure backward compatibility for existing clients.
  • v2: This is your new version, which is a completely separate API configuration that you can edit independently.

4. Test Your Versions

• Select the v2 API and go to the Test tab.
  • Notice the Request URL now includes /v2/.
  • Send a request. It should succeed with a 200 OK.
• Now, select the Original API and go to its Test tab.
  • The Request URL does not have a version segment.
  • Send a request. This should also succeed.

You have successfully created a new version of your API while maintaining backward compatibility for existing consumers! You can now make breaking changes to the v2 API (e.g., add or remove operations, apply different policies) without affecting anyone using the Original version.

Conclusion

Congratulations on completing the API Management module! In this lesson, you mastered the critical skill of API versioning. You now understand how to manage your API's lifecycle, introduce breaking changes safely, and support multiple versions simultaneously.

Key Takeaways:

• API versioning is essential for evolving an API without disrupting existing clients.
• Azure API Management supports three versioning schemes: Path, Query string, and Header.
• Versions are used for breaking changes, allowing multiple API contracts to be live at once.
• Revisions are for non-breaking changes, providing a safe way to edit and deploy updates to a specific version.
• When you add a version to an unversioned API, APIM automatically creates an Original version to ensure backward compatibility. All versions of a logical API are grouped into a Version Set.

Next Steps

With API Management now covered, you are equipped to build, secure, and manage robust API solutions in Azure.

In our next module, we will explore another powerful paradigm for cloud development: Developing Containerized Solutions. We'll begin by diving into the fundamentals of Docker, learning how to package your .NET applications into portable, efficient containers, and setting the stage for deploying them on Azure.