This chapter covers API versioning in Azure API Management, a critical skill for the AZ-204 exam. You will learn how to design, implement, and manage multiple versions of your APIs to support non-breaking changes and client coexistence. API Management versioning appears in roughly 5-10% of exam questions, often integrated with policies, revisions, and developer portal scenarios. Mastery of versioning strategies and their trade-offs is essential for passing the exam.
Jump to a section
Imagine a hotel that has been operating for decades. Over time, they renovate floors and change room layouts. Each guest receives a key card that specifies not just the room number, but also the version of the lock system installed on that floor. The front desk maintains a registry: for each version, they know exactly which locks, which key card readers, and which floor layouts are in use. When a guest checks in, the system checks the guest's reservation (API key) and issues a key card (API response) that matches the lock version on the assigned floor. If a guest returns after a renovation, their old key card might not work on a floor that has been upgraded to a new lock system—unless the front desk issues a new key card compatible with the current version. Similarly, API versioning in Azure API Management allows clients to continue using an older version of an API while the backend evolves. The API Management gateway acts like the front desk: it inspects the version identifier (in the URL, header, or query string) and routes the request to the appropriate backend implementation. Just as the hotel maintains multiple lock versions, the gateway can host multiple API versions simultaneously. When a client sends a request with version 'v1', the gateway knows to use the v1 backend logic, even if the v2 backend has completely different business rules. This prevents breaking changes for existing clients while allowing innovation.
What Is API Versioning and Why Does It Exist?
API versioning is the practice of managing changes to an API over time without breaking existing consumers. As your API evolves—adding new fields, changing request/response schemas, deprecating endpoints—you need a way to allow clients to continue using the old contract while you roll out the new one. Without versioning, any change could break all clients, forcing them to update simultaneously, which is impractical in distributed systems.
Azure API Management (APIM) provides built-in versioning support that allows you to define multiple versions of the same API and route requests to the correct version based on a version identifier. The version identifier can be specified in the URL path, a query string parameter, or an HTTP header. APIM also supports version sets, which group related versions together and allow you to manage them as a logical unit.
How API Versioning Works Internally in Azure API Management
When you enable versioning for an API in APIM, the service creates a version set. A version set is a container that holds all versions of a particular API. Each version is represented by a separate API entity within the APIM instance, but they are linked through the version set. The version set defines the scheme used to identify the version (path, query, or header) and the version identifier value for each version.
Here's the step-by-step mechanism:
Define a Version Set: In the Azure portal or via ARM templates, you create a version set. You specify the name, description, and the versioning scheme (e.g., path, query, or header). For example, you might create a version set called "MyAPI" with a path-based scheme.
Create Versions: For each version (e.g., v1, v2), you create a new API within the version set. Each API has its own backend URL, policies, and operations. The API is associated with the version set, and you provide a version identifier (e.g., "v1", "v2").
Client Request Routing: When a client sends a request to the APIM gateway, the gateway inspects the request for the version identifier according to the version set's scheme. For path-based versioning, the version identifier appears in the URL path (e.g., /api/v1/products). For query-based, it's a query parameter (e.g., /api/products?api-version=v1). For header-based, it's an HTTP header (e.g., Api-Version: v1).
Gateway Resolution: The gateway uses the version identifier to select the correct API version. It then applies the policies defined for that version and forwards the request to the corresponding backend.
Default Version: You can designate a default version for a version set. If a request does not include a version identifier, it is routed to the default version. This is useful for backward compatibility.
Key Components, Values, and Defaults
Versioning Schemes: Three options: path, query, header. Path is most common and RESTful. Query is simple but can be overlooked. Header is cleanest for URL structure but requires client cooperation.
Path: version identifier appears in URL path, e.g., /api/v1/products. Default path segment name is v1 but you can customize.
Query: version identifier is a query parameter, e.g., /api/products?api-version=v1. Default parameter name is api-version.
Header: version identifier is in an HTTP header, e.g., Api-Version: v1. Default header name is Api-Version.
Version Identifiers: Any string, but typically semantic like "v1", "v2", "2021-05-01". Must be unique within a version set.
Version Set: Acts as a logical grouping. It has a name, description, and scheme. The scheme is set at the version set level and applies to all versions in that set.
Default Version: You can set one version as the default. Requests without a version identifier are routed to the default.
Revisions vs. Versions: Revisions are for non-breaking changes within a version (e.g., bug fixes). Versions are for breaking changes. Revisions can be made current without changing the version identifier. Versions require a new identifier.
Configuration and Verification Commands
You can manage versioning using Azure CLI, PowerShell, ARM templates, or the portal.
Azure CLI Example:
Create a version set:
az apim api versionset create --resource-group myResourceGroup --service-name myAPIM --name myVersionSet --scheme path --display-name "My Version Set"Create a version (v1) within the version set:
az apim api create --resource-group myResourceGroup --service-name myAPIM --api-id my-api-v1 --path /api/v1 --display-name "My API v1" --protocols https --service-url https://backend.example.com/v1 --api-version-set-id myVersionSet --api-version v1Create another version (v2):
az apim api create --resource-group myResourceGroup --service-name myAPIM --api-id my-api-v2 --path /api/v2 --display-name "My API v2" --protocols https --service-url https://backend.example.com/v2 --api-version-set-id myVersionSet --api-version v2Set a default version:
az apim api update --resource-group myResourceGroup --service-name myAPIM --api-id my-api-v1 --set apiVersionSetId=myVersionSet --set isCurrent=truePowerShell Example:
New-AzApiManagementApiVersionSet -ResourceGroupName "myResourceGroup" -ServiceName "myAPIM" -Name "myVersionSet" -Scheme "Path"Create API version:
New-AzApiManagementApi -ResourceGroupName "myResourceGroup" -ServiceName "myAPIM" -ApiId "my-api-v1" -Path "/api/v1" -DisplayName "My API v1" -Protocols @("https") -ServiceUrl "https://backend.example.com/v1" -ApiVersionSetId "myVersionSet" -ApiVersion "v1"Interaction with Related Technologies
Policies: Policies can be applied at the version level, allowing different rate limits, caching, or transformation rules per version. For example, you might have stricter rate limits on older versions to encourage migration.
Developer Portal: The developer portal displays all versions of an API, allowing developers to explore and test specific versions. You can also mark versions as deprecated in the portal.
Backend Services: Each version can point to a different backend service URL. This allows you to deploy a new version of your backend without affecting the old one.
API Management Revisions: Revisions are separate from versions. Revisions are for non-breaking changes within a version. You can have multiple revisions per version, and you can make a revision current without changing the version identifier. Versions are for breaking changes and require a new identifier.
Best Practices
Use path-based versioning for simplicity and RESTful design.
Always set a default version to handle requests without a version identifier.
Deprecate old versions gradually: use policies to warn clients, then eventually block.
Keep version identifiers meaningful (e.g., date-based like 2021-05-01 or semantic like v2).
Use version sets to group related versions for easier management.
Test each version independently to ensure backward compatibility.
Define a Version Set
First, create a version set in Azure API Management. This is a logical container that groups all versions of an API. In the Azure portal, navigate to APIs > Version Sets > Add. Provide a name (e.g., 'MyAPI'), description, and select the versioning scheme (path, query, or header). The scheme determines how clients will specify the version in their requests. For path-based, the version identifier appears in the URL path (e.g., /api/v1). For query-based, it's a query parameter (e.g., ?api-version=v1). For header-based, it's an HTTP header (e.g., Api-Version: v1). The scheme is fixed for the version set and cannot be changed later.
Create the First API Version
Within the version set, create the first version (e.g., v1). This is a full API definition with its own backend URL, operations, policies, and product associations. When creating the API, you specify the version set and the version identifier (e.g., 'v1'). The API path will include the version identifier if using path-based scheme. For example, the API path might be '/api/v1'. The backend URL can be different from other versions, allowing you to point to a legacy backend. You can also set this version as the default version, meaning requests without a version identifier will be routed to it.
Add Subsequent API Versions
To introduce breaking changes, create a new version (e.g., v2) within the same version set. This version will have its own backend URL, operations, and policies. The version identifier must be unique within the version set. You can copy operations from an existing version to speed up creation. Each version is independent, so you can modify the schema, add new endpoints, or change business logic without affecting v1 clients. The gateway will route requests based on the version identifier in the request (path, query, or header).
Configure Version Routing
The APIM gateway automatically routes requests to the correct version based on the version identifier. For path-based versioning, the gateway strips the version segment from the URL before forwarding to the backend. For example, a request to '/api/v2/products' is routed to the v2 backend, and the backend receives '/products'. For query-based, the gateway removes the query parameter before forwarding. For header-based, the header is removed. You can customize the version identifier name (e.g., 'version' instead of 'v1') but must be consistent across versions. The routing is transparent to the client; they just need to include the version identifier.
Manage Lifecycle and Deprecation
Over time, you may want to deprecate old versions. APIM does not automatically block deprecated versions; you must manually remove them or use policies to reject requests. Common practice: add a policy that checks the version and returns a warning header or a 410 Gone status for deprecated versions. You can also remove the version from the developer portal or set it as not current. When a version is no longer needed, you can delete it from the version set. However, ensure no clients are actively using it. You can monitor usage via Azure Monitor logs.
Enterprise Scenario 1: E-Commerce Platform Migration
A large e-commerce company has an API for product catalog that has been in production for years. They need to introduce a new pricing model that changes the response schema. They cannot break existing mobile apps and third-party integrations. They use Azure API Management with path-based versioning. They create a version set 'ProductCatalog' with v1 pointing to the old backend and v2 pointing to the new microservice. The v2 API has additional fields like 'discountPrice' and 'currency'. They set v1 as default so that clients not specifying a version still work. They update the developer portal to show both versions. Over six months, they monitor usage and gradually deprecate v1 by adding a policy that returns a deprecation warning header. After confirming no traffic, they delete v1. This approach allowed a seamless transition without downtime.
Enterprise Scenario 2: Financial Services API with Date-Based Versioning
A bank provides an API for account transactions. They release a new version every quarter with regulatory changes. They use query-based versioning with a date string (e.g., '2024-01-01'). The version set uses the query scheme with parameter name 'api-version'. Each version has its own backend service URL. The bank sets the latest version as default. They use APIM policies to enforce minimum TLS version and rate limits per version. They also use Azure Monitor to track which versions are being used. When a version is two quarters old, they add a policy that returns a 400 error with a message to upgrade. This ensures compliance and security.
Common Pitfalls
Forgetting to set a default version: If no default is set and a request lacks a version identifier, APIM returns a 404 or 400 error. Always set a default.
Inconsistent version identifiers: Using different schemes or identifier formats across versions in the same set causes confusion. Stick to the scheme defined in the version set.
Not updating backend URLs: When creating a new version, ensure the backend URL points to the correct service. A common mistake is copying the old backend URL.
Ignoring policy inheritance: Policies can be applied at the API level and also at the product level. Ensure that version-specific policies are correctly scoped.
What AZ-204 Tests on API Versioning (Objective 5.1)
The exam focuses on understanding the difference between revisions and versions, when to use each, and how to configure versioning in Azure API Management. Specific topics include:
Versioning schemes (path, query, header) and when to choose each.
Creating version sets and associating APIs.
Setting a default version.
Using revisions for non-breaking changes vs. versions for breaking changes.
Configuring version identifiers.
Common Wrong Answers and Why
Choosing 'Revision' when the question describes a breaking change: Revisions are for non-breaking changes (bug fixes, minor updates). Breaking changes require a new version. Candidates often confuse the two because both involve creating a new API entity. Remember: revisions do not change the version identifier; versions do.
Selecting 'Header-based versioning' for a mobile app scenario where the client cannot easily add custom headers: Header-based versioning requires clients to set a custom HTTP header. Some mobile app frameworks make this difficult. Path-based is more universal. The exam may test this nuance.
Thinking that versioning can only be done at the API level: Versioning is also supported at the product level? Actually, versioning is per API, not per product. Products group APIs, but versioning is defined on the API itself. Candidates may incorrectly assume a product can have multiple versions.
Specific Numbers and Terms
The default query parameter name is api-version.
The default header name is Api-Version.
Path-based versioning uses a URL segment like /v1 or /v2.
A version set can have up to 100 versions (soft limit, can be increased).
The version identifier can be any string, but typically v1, v2, or date-based like 2021-05-01.
Edge Cases
Version identifier in path with multiple segments: If your API path is /api/v1/products, the version segment is v1. Ensure the path does not conflict with other APIs.
Default version not set: If no default version is set, requests without a version identifier will fail. The exam may ask what happens in this scenario.
Changing the versioning scheme after creation: You cannot change the scheme of a version set after creation. You must create a new version set.
How to Eliminate Wrong Answers
If the question mentions 'non-breaking change', think 'revision' not 'version'.
If the question says 'breaking change' or 'new contract', think 'version'.
If the question describes a scenario where clients cannot easily change their request format, prefer path-based versioning.
Remember that versions are independent APIs; each has its own backend URL and policies.
API versioning in Azure API Management allows multiple versions of an API to coexist, each with its own backend URL and policies.
Versioning schemes: path, query, header. Choose path for simplicity and RESTful design.
Version sets group related versions; you cannot change the scheme after creation.
Always set a default version to handle requests without a version identifier.
Revisions are for non-breaking changes; versions are for breaking changes.
The default query parameter name is 'api-version'; default header name is 'Api-Version'.
Up to 100 versions per version set (soft limit).
Versions are independent; each has its own lifecycle and can be deprecated separately.
Use Azure Monitor to track usage and decide when to deprecate old versions.
Policies can be applied per version to enforce different rules (e.g., rate limiting).
These come up on the exam all the time. Here's how to tell them apart.
Path-based Versioning
Version identifier appears in URL path, e.g., /api/v1/products.
RESTful and intuitive; version is part of the resource URI.
Requires changes to URL structure; clients must update their base URL.
Easy to cache and route at the gateway level.
Most commonly used in public APIs.
Query-based Versioning
Version identifier is a query parameter, e.g., /api/products?api-version=v1.
URL path remains unchanged; only query string differs.
Can be omitted by clients if a default version is set.
May be overlooked by clients or proxies; caching can be tricky.
Simple to implement without changing routes.
Revisions
Used for non-breaking changes (bug fixes, minor updates).
Multiple revisions exist within a single version.
No change to version identifier; client sees same API.
Can be made current without affecting clients.
Revisions are numbered (e.g., revision 1, 2).
Versions
Used for breaking changes (schema changes, new endpoints).
Each version is a separate API entity with its own identifier.
Version identifier changes (e.g., v1 to v2).
Clients must opt-in to new version by changing identifier.
Versions are managed via version sets.
Mistake
Revisions and versions are the same thing.
Correct
Revisions are for non-breaking changes within a single version. They allow you to make changes to an API without changing the version identifier. Versions are for breaking changes and require a new version identifier. Revisions can be made current without affecting the version number; versions create a separate API entity.
Mistake
You can change the versioning scheme of a version set after creation.
Correct
Once a version set is created with a scheme (path, query, or header), you cannot change it. You must create a new version set if you need a different scheme. This is a common exam trap.
Mistake
A version set can only contain one version.
Correct
A version set is designed to hold multiple versions. You can have up to 100 versions per set (soft limit). Each version is a separate API with its own backend and policies.
Mistake
If you don't specify a default version, requests without a version identifier will be routed to the first version created.
Correct
If no default version is set, requests without a version identifier will result in an error (404 or 400). The gateway does not automatically route to any version. You must explicitly set a default version.
Mistake
Versioning is only supported in the Azure portal, not via CLI or ARM.
Correct
Versioning is fully supported via Azure CLI, PowerShell, ARM templates, and REST API. You can automate the creation and management of version sets and versions.
Reveal each answer, then mark whether you got it right. Score 60%+ to unlock the next chapter.
A revision is a non-breaking change to an API, such as a bug fix or minor update, that does not change the version identifier. You can have multiple revisions per version, and you can make any revision current without affecting the version number. A version is a breaking change that requires a new version identifier (e.g., v1 to v2). Versions are separate API entities grouped in a version set. On the exam, remember: revisions = non-breaking, versions = breaking.
In the Azure portal, go to the version set, select the version you want as default, and set it as 'Default'. Alternatively, using Azure CLI, you can update the API with the `--is-current` flag set to true. If no default version is set, requests without a version identifier will result in an error. Always set a default to ensure backward compatibility.
No, the versioning scheme is fixed at creation time. To use a different scheme, you must create a new version set. This is a common exam trap. Plan your versioning strategy carefully before creating the version set.
Products group APIs, and subscriptions grant access to products. Versioning is per API, not per product. When you add a versioned API to a product, all versions of that API become available to subscribers of that product. You can control access to specific versions by using separate products or by applying policies that check the version identifier.
The gateway will return an error, typically a 404 Not Found or 400 Bad Request, because it cannot determine which version to route to. To avoid this, always set a default version for your version set.
No, each API can belong to only one version set. If you need different versioning schemes for different endpoints, you would need to create separate APIs (e.g., one for path-based, one for header-based) and manage them independently.
Deprecation is not automatic. You can add a policy that returns a deprecation warning header (e.g., 'Warning: 299 - "Deprecated"') or a 410 Gone status. You can also remove the version from the developer portal. Eventually, you can delete the version when no clients are using it. Monitor usage with Azure Monitor.
You've just covered API Versioning in Azure API Management — now see how well it sticks with free AZ-204 practice questions. Full explanations included, no account needed.
Done with this chapter?