API Management revision - Azure Glossary

Understand the concept

In plain English

An API Management revision is a safe working copy of an API for changes that should not break consumers. You create a revision, adjust operations, descriptions, policies, or backend settings, test the changes, and then make that revision current when it is ready. Existing consumers keep using the current revision until promotion. In plain terms, a revision is a release-management tool for controlled API updates, not a new major version for breaking contract changes. Teams should document the owner, environment, and expected behavior.

Why it matters

API Management revisions matter because gateway configuration changes can be risky even when the backend contract is not breaking. A small policy edit, route adjustment, documentation correction, or backend URL change can interrupt traffic if applied directly to the current API. Revisions give teams a place to test the change, collect approvals, compare behavior, and promote deliberately. They also separate nonbreaking improvements from versioning decisions. Without revisions, teams often choose between unsafe live edits and unnecessary new versions that confuse consumers and clutter the developer portal. Clear ownership, evidence, and rollback notes turn the concept into something teams can operate safely.

Official wording and source

An API Management revision is a controlled, nonbreaking copy of an API that lets teams edit and test changes before making that revision current.

Open Microsoft Learn

Technical context

Technically, revisions exist inside an API Management API and allow separate editable API configuration while the service continues serving the current revision. Revisions can have different operations, policies, documentation, and backend settings, but they represent the same API contract family. A revision can be accessed for testing with a revision identifier before promotion. When made current, API Management can publish a change-log entry in the developer portal so consumers understand what changed without switching to a different version.

Exam context

Compare with

API Management API

Where it is used

Where you see it

You see it in API Management when an API has multiple revisions, with one marked current and others used for testing or pending promotion. during formal reviews
You see it in developer-portal change logs when a nonbreaking API update is promoted and consumers need a clear record of what changed. before production rollout
You see it during release reviews when policy, operation, backend, or documentation changes must be tested without disturbing existing API consumers. with approved ownership with approved ownership

Common situations

Move events or messages between applications without direct synchronous dependencies.
Build workflows that coordinate systems, APIs, data, and human approvals.
Troubleshoot dead-letter, retry, ordering, throughput, or subscription behavior.
Document how producers and consumers interact in a production system.

Illustrative Azure scenarios

These examples show how the concept can affect design and operations. They are illustrative scenarios, not customer claims.

Scenario 01 Safer payment policy rollout Scenario, objectives, solution, measured impact, and takeaway.

Scenario

Fourth Coffee Payments, a fintech platform, needed to add stronger fraud headers without risking live checkout traffic.

Goals

test a gateway policy change before production
keep existing payment clients on the current API
promote only after synthetic transaction success
retain rollback evidence for audit

Approach using API Management revision

The API team created a new API Management revision for the checkout API. In that revision, they added an inbound policy that required a fraud-correlation header and forwarded it to the payment backend. Test clients called the revision-specific endpoint while production traffic stayed on the current revision. The team compared policy XML, operation lists, diagnostics, and synthetic transaction results before promotion. When the revision became current, they posted a developer-portal change-log entry and kept the previous revision available for rollback. Monitoring watched checkout latency, validation failures, and backend errors for the next release window. The runbook named API Management revision ownership, rollback evidence, expected monitoring signals, and the first support checks after rollout. Reviewers compared production and nonproduction evidence so the team could separate configuration problems from application defects quickly.

Potential outcomes

checkout traffic stayed uninterrupted during testing
synthetic transactions passed before the revision became current
audit reviewers received policy exports and promotion history
rollback evidence was available within minutes if errors appeared

What to learn

Revisions make nonbreaking API Management changes safer by separating testing from the current consumer-facing configuration.

Scenario 02 Public records API documentation fix Scenario, objectives, solution, measured impact, and takeaway.

Scenario

CivicWorks County, a public-sector agency, needed to correct endpoint descriptions and examples without creating a new public API version.

Goals

update documentation and examples safely
avoid forcing developers to switch version identifiers
verify no operations were accidentally changed
publish a clear change note in the developer portal

Approach using API Management revision

The digital services group used an API Management revision for the records-search API. They updated operation descriptions, request examples, and a minor response example while keeping methods, routes, policies, and backend URLs unchanged. Reviewers compared the revision against the current API and tested the developer-portal documentation with two partner teams. CLI export evidence confirmed that no operations or security policies changed. After approval, the team made the revision current and posted a change-log note describing the documentation correction. The old revision was retained until the next release review, then removed after no support tickets appeared. The runbook named API Management revision ownership, rollback evidence, expected monitoring signals, and the first support checks after rollout.

Potential outcomes

partner confusion tickets fell 28 percent after corrected examples
no client was required to change API version or base URL
security reviewers confirmed policy parity before promotion
the developer portal displayed a clear nonbreaking change note

What to learn

A revision is useful when the API contract stays stable but the gateway configuration or documentation needs a controlled update.

Scenario 03 Backend URL migration rehearsal Scenario, objectives, solution, measured impact, and takeaway.

Scenario

Northstar Logistics, a shipping company, needed to move a tracking API to a new regional backend with minimal disruption.

Goals

test backend routing before current traffic changed
compare latency between old and new backend paths
keep tracking clients unaware during validation
rollback quickly if regional errors increased

Approach using API Management revision

Architects created an API Management revision for the shipment-tracking API and changed the backend URL only in the candidate revision. Internal test subscriptions called the revision endpoint from multiple regions while production consumers remained on the current revision. The team reviewed gateway diagnostics, backend health, timeout behavior, and operation-level latency. After confirming the new backend was faster and stable, they promoted the revision during a low-traffic window. The previous revision and exported configuration were kept ready for rollback. Support dashboards were annotated so responders could link any tracking errors to the revision promotion time. The runbook named API Management revision ownership, rollback evidence, expected monitoring signals, and the first support checks after rollout.

Potential outcomes

regional p95 tracking latency improved 22 percent after promotion
no customer integrations changed their base API version
rollback readiness was confirmed before the change window
gateway diagnostics separated backend errors from client request problems

What to learn

Revisions help teams validate gateway-facing changes before exposing every consumer to the new path.

Azure CLI

Azure CLI is useful for API Management revision because it gives operators repeatable evidence instead of one-off portal screenshots. Teams can inspect configuration, compare environments, export review data, and automate safe changes before current API traffic changes.

Useful for

Inventory API Management API revision across resource groups and subscriptions before a release, migration, audit, or incident review.
Show the current API Management API revision configuration and capture IDs, scopes, names, status fields, or route settings for change evidence.
Update nonproduction API Management API revision settings through a scripted path, then compare the result with the approved production baseline.
Export command output as JSON so platform, security, and application teams can review the same facts during troubleshooting.

Before you run a command

Confirm tenant, subscription, resource group, service name, and environment because similarly named resources often exist in several stages.
Use an identity with the least privileges required to read or change the resource, and record whether the command is read-only.
Check whether the operation affects production traffic, security boundaries, authentication, routing, throttling, or customer-visible behavior.
Choose JSON output for evidence, and save the previous configuration before running commands that create, update, or delete settings.

What the output tells you

Resource IDs and names prove which Azure boundary was inspected, preventing mistakes caused by the wrong subscription or instance.
Status, version, route, identity, or policy fields show whether the live configuration matches the intended design or release record.
Missing values, empty arrays, or unexpected defaults often reveal incomplete deployment, portal-only drift, or permissions hiding part of the result.
Timestamps, provisioning states, and nested properties help separate a failed change from a working configuration that simply needs propagation time.

Mapped commands

Apim operations

direct

az apim list --resource-group <resource-group>

az apimdiscoverIntegration

az apim show --name <apim-name> --resource-group <resource-group>

az apimdiscoverIntegration

az apim api list --service-name <apim-name> --resource-group <resource-group>

az apim apidiscoverIntegration

az apim api import --service-name <apim-name> --resource-group <resource-group> --path <path> --specification-url <url> --specification-format OpenApi

az apim apiprovisionIntegration

Architecture context

Security: Security reviews should treat revisions as deployable API configurations. A draft revision may relax token validation, point to a test backend, expose a temporary operation, or omit a policy inherited by the current revision. Operators must know which revision is current, who can edit revisions, and whether test revision URLs are accessible beyond the intended audience. Before promotion, compare security policies, products, named values, certificate requirements, and diagnostics. A revision should never become current until its authentication, authorization, logging, and backend routing match the approved production design. Security reviewers should confirm the approved scope, identity path, and logging behavior before production release. Reliability: Reliability improves when revisions are used to test gateway changes before production promotion. Teams can validate operation matching, policy evaluation, backend connectivity, response transformations, and developer-portal descriptions without disturbing current consumers. Promotion still needs a rollback plan: the previous current revision and policy export should be available if errors appear. Monitoring should track response codes and latency immediately after a revision becomes current. Revisions are not substitutes for backend release discipline, but they reduce blast radius for API Management configuration changes that otherwise happen live. Reliable teams test the setting in nonproduction, document rollback values, and monitor the first production signals after change. Operations: Operational work around revisions includes creating revisions for planned changes, testing revision-specific URLs, exporting definitions, approving policy differences, making one revision current, and posting change-log notes. Operators should document which revision is current, which are obsolete, and whether old revisions can be deleted. Incident response should check recent revision promotions before investigating backend code. Release managers should align revision promotion with backend deployment windows, synthetic tests, and portal communication so consumers are not surprised by changed examples, response shapes, or route behavior. Runbooks should include owners, commands, expected outputs, review cadence, and the first checks to perform during incidents. That makes support work repeatable instead of dependent on memory. Cost: Revisions do not usually add direct cost, but unmanaged revisions create operational waste and confusion. Multiple stale revisions can increase review time, obscure which policy is authoritative, and lead teams to test the wrong gateway path. Bad revisions can also cause retries, logging spikes, and backend load if promoted without validation. Keeping revision counts tidy, documentation current, and diagnostics focused reduces wasted engineering time. FinOps teams should look at revision-related incidents when API traffic or monitoring cost rises after what appeared to be a minor gateway change. Cost owners should review usage, diagnostics, and duplicated environments whenever the setting changes or traffic grows. Performance: Performance impact comes from the configuration contained in a revision. A new revision might add policy transformations, route to a slower backend, disable caching, or change timeout behavior. Testing should compare latency and error patterns between the current revision and candidate revision before promotion. After promotion, dashboards should show operation-level latency so teams can catch regressions quickly. Revisions themselves are not a performance feature, but they provide a controlled path to evaluate performance-sensitive gateway changes before they affect all consumers. Performance reviews should compare before-and-after telemetry and separate gateway, identity, network, and backend effects. That prevents teams from blaming the wrong layer when latency changes.

Security: Security reviews should treat revisions as deployable API configurations. A draft revision may relax token validation, point to a test backend, expose a temporary operation, or omit a policy inherited by the current revision. Operators must know which revision is current, who can edit revisions, and whether test revision URLs are accessible beyond the intended audience. Before promotion, compare security policies, products, named values, certificate requirements, and diagnostics. A revision should never become current until its authentication, authorization, logging, and backend routing match the approved production design. Security reviewers should confirm the approved scope, identity path, and logging behavior before production release.
Cost: Revisions do not usually add direct cost, but unmanaged revisions create operational waste and confusion. Multiple stale revisions can increase review time, obscure which policy is authoritative, and lead teams to test the wrong gateway path. Bad revisions can also cause retries, logging spikes, and backend load if promoted without validation. Keeping revision counts tidy, documentation current, and diagnostics focused reduces wasted engineering time. FinOps teams should look at revision-related incidents when API traffic or monitoring cost rises after what appeared to be a minor gateway change. Cost owners should review usage, diagnostics, and duplicated environments whenever the setting changes or traffic grows.
Reliability: Reliability improves when revisions are used to test gateway changes before production promotion. Teams can validate operation matching, policy evaluation, backend connectivity, response transformations, and developer-portal descriptions without disturbing current consumers. Promotion still needs a rollback plan: the previous current revision and policy export should be available if errors appear. Monitoring should track response codes and latency immediately after a revision becomes current. Revisions are not substitutes for backend release discipline, but they reduce blast radius for API Management configuration changes that otherwise happen live. Reliable teams test the setting in nonproduction, document rollback values, and monitor the first production signals after change.
Performance: Performance impact comes from the configuration contained in a revision. A new revision might add policy transformations, route to a slower backend, disable caching, or change timeout behavior. Testing should compare latency and error patterns between the current revision and candidate revision before promotion. After promotion, dashboards should show operation-level latency so teams can catch regressions quickly. Revisions themselves are not a performance feature, but they provide a controlled path to evaluate performance-sensitive gateway changes before they affect all consumers. Performance reviews should compare before-and-after telemetry and separate gateway, identity, network, and backend effects. That prevents teams from blaming the wrong layer when latency changes.
Operations: Operational work around revisions includes creating revisions for planned changes, testing revision-specific URLs, exporting definitions, approving policy differences, making one revision current, and posting change-log notes. Operators should document which revision is current, which are obsolete, and whether old revisions can be deleted. Incident response should check recent revision promotions before investigating backend code. Release managers should align revision promotion with backend deployment windows, synthetic tests, and portal communication so consumers are not surprised by changed examples, response shapes, or route behavior. Runbooks should include owners, commands, expected outputs, review cadence, and the first checks to perform during incidents. That makes support work repeatable instead of dependent on memory.

Common mistakes

Changing API Management revision in production before proving the exact scope, owner, and dependency chain that will be affected.
Trusting a portal label without exporting the underlying JSON, especially when workspaces, revisions, identities, or environments are involved.
Assuming a successful command means the application path works; many Azure settings still require client, network, or policy validation.
Ignoring rollback evidence, which turns a small configuration error into a long outage or audit dispute.