Why API versioning strategy is important

1. Why API versioning strategy is important

In this video, we will cover API versioning and canary releases in API Management.

2. Introduction to API versioning

Think of your API like a public railway. Suppose you have an existing track and you want to build a new track that covers the same route, but improves it.

3. API versioning fundamentals

You create a new line when you make breaking changes that would confuse riders on the old line. Revisions are maintenance tune-ups on the same line: you're fixing tracks, adding signage, or smoothing the ride without changing where the train goes. While you are building a new track, the passengers can carry on using the old one. In Azure API Management, versions live in a "version set" while revisions let you edit safely, test, and then mark one as "current" when you're ready.

4. Version signposting

Next, how do train drivers know which line to take? APIM supports three signposting strategies. URL path versioning puts the line in the address, like /v2/orders, which is as clear as a street sign. Header versioning hides the line on the ticket, e.g., Api-Version: 2, which keeps URLs clean but requires clients to set headers correctly. It's popular for programmatic clients as it keeps the resource URL clean and stable. Query-string versioning writes the line on the envelope, such as ?api-version=2, is very flexible and great for links or simple test scenarios. You choose the scheme in the version set configuration and keep it consistent across your API family so developers don’t get lost.

5. Version vs revision

As well as creating new versions of the API, we can do updates to the same API version. This is similar to improving an existing railway track without building a new one. You still improve things, but you aren't making any breaking changes. This process is known as creating a new revision.

6. Canary releases

Now, let's switch metaphors from the railway to the kitchen to talk about canary releases. A canary release is like serving a new recipe to a few tables before updating the whole menu. In APIM, you create a new revision, test it privately, and then expose it to a limited audience, perhaps a pilot product or a subset of callers, while everyone else stays on the current revision. You can even target a specific revision via a special URL that has the revision number. If we go back to the railway analogy, this lets testers ride the “maintenance track” without affecting the main line. When the dish tastes great, you make the revision current; if feedback sours, you roll back instantly by switching the previous revision back to current.

7. Key concepts to remember

To truly master APIM, you are expected to know when to use versions versus revisions, how to pick and configure a versioning scheme, and how to roll changes forward or back with minimal disruption. Mastering these tools means you can evolve your API confidently: keep legacy riders on the old line, onboard new riders to the new line, and perform track maintenance safely in between without requiring any service outage.

8. Let's practice!

Let's see how these concepts are applied in practice.

Create Your Free Account

By continuing, you accept our Terms of Use, our Privacy Policy and that your data is stored in the USA.