An API is a promise you have to keep changing
A published API is a promise made to people you will never meet: call this path, send this shape, get this shape back. Their code is written against that promise, and it keeps running only as long as you keep it. Yet the API must change — a new field, a bug fixed, a rename the backend needed — and every change is a chance to break someone who built against the old promise and went home. The whole discipline of this part is changing the thing without breaking the strangers, and it turns on one distinction that decides everything downstream: is this change breaking or non-breaking?
A non-breaking change is one a caller written against the old shape survives unaltered: adding an optional field, fixing a bug, tuning a policy. A breaking change is one that would make that caller's existing code fail: removing or renaming a field, changing a type, making an optional parameter required. APIM gives you a distinct tool for each — and using the wrong one is how a "small fix" becomes three partners' outage at once:
- Revision
- For testing and releasing changes to one API. A non-current revision has its own test URL. You can make it current when ready and switch back if needed. Protect its test URL: by default it uses the same security settings and can be called by anyone who has access to it.
- Version
- For breaking changes. A separate, consumer-visible variant — v1, v2 — that a caller chooses. Old and new run side by side, so nobody is forced to move on your schedule.
- Deprecation
- A planned end of support: notify consumers, monitor calls across the routes they use, confirm migrations, and send a final notice before shutdown. Traffic reports help, but do not reveal every consumer behavior.
- Observability
- Configured APIM diagnostics, Azure Monitor, Application Insights, and built-in analytics show different views of calls, errors, and latency. Choose the data source and retention that fit the question you need to answer.
Which caller breaks?
Before: { "id": 42, "name": "Alpine 7 boot", "price": 129.00 }
After: { "id": 42, "name": "Alpine 7 boot", "price": { "amount": 129.00, "currency": "USD" } }
The warehouse reads price as a number. The courier ignores price entirely. Predict who breaks, then decide whether this change needs a revision (§2) or a new version (§3).
Check your answer
The warehouse breaks: its code expects a number and now gets an object. The courier is fine. Changing a field's type is a breaking change, so it needs a new version callers opt into. Adding a new field, say "currency": "USD" beside the old price, would not break either, and a revision would do.
Revisions — change you can take back
A revision lets you edit a copy of an API definition and policy while the current revision continues to serve requests sent to the normal API URL. A non-current revision also has its own test URL, formed with ;rev=N. That URL is callable; by default it has the same security settings as the current revision. Use an IP filter or take the revision offline if it must stay private. After testing, make it current so requests to the normal URL use the new revision. You can then make the previous revision current again if the change causes problems.1
The useful property is rollback: if a release misbehaves, make the prior revision current again. This changes which revision receives requests sent to the normal API URL; it does not undo backend deployments, data changes, or side effects caused by the new policy. Test the full change and plan a separate rollback for anything outside APIM.
A change with no previous is a change with no undo.
Versions — change the caller chooses
When a change would break existing callers, publish a version so old and new API shapes can run side by side. APIM can distinguish versions by a path segment, header, or query parameter. For example, one caller might request /catalog/v1 and another /catalog/v2. Keep v1 available while consumers update and test v2 before directing production calls to it. The version set defines how APIM recognizes each version; it does not migrate callers or prove the new version works for them.3
| Revision | Version | |
|---|---|---|
| Typical use | Test and release a non-breaking change | Offer a breaking API shape separately |
| Consumer visible? | Usually no change to the normal URL; a test revision URL is callable | Yes — the request selects the version |
| Selected by | You (make one current) | The caller (path / header / query) |
| Run in parallel? | One is current at a time | v1 and v2 live at once |
| Undo | Make prior revision current | Retire a version after traffic moves |
| Typical trigger | Bug fix, added optional field, policy tweak | Removed / renamed field, changed type, new required param |
Versions let you plan a deprecation instead of forcing an immediate switch. Publish and test v2, tell consumers when support for v1 is expected to end, and watch calls to both versions. Before removing v1, check that the telemetry covers all gateways and consumers, includes the full period you care about, and has no gaps from sampling or retention limits. A zero count in one dashboard is evidence for a time window, not proof that nobody will ever call v1 again. Coordinate with consumers and provide a final notice before shutdown.
You can create a version from a revision. This is useful when you want to build a breaking shape in a draft, then publish it as a separate version. Remember that the revision test URL can be called directly unless you protect it. Creating v2 does not automatically make it current for existing callers; configure the version set and test the selected URL before announcing it.
Play it through
Three minutes. Rename a field without breaking the partner who calls it today: build the change on a revision, then publish it as a version a caller opts into. Then read the traffic before retiring v1, not the calendar. It plays on its own and stops when it needs your hands.
Observability — seeing before you are told
Observability means collecting enough information to understand how the API behaves. In APIM, the built-in analytics provides reports about traffic, consumers, response times, and failures. APIM diagnostics can also send request records to Application Insights or a Log Analytics workspace when configured. Those records can include the API, operation, response code, and timing fields. The exact details depend on the diagnostic settings; body and header logging are separate options, can expose sensitive data, and can affect performance. Application Insights may sample records to control volume, so do not assume every request is present. Backend tracing requires the backend or another component to emit correlated telemetry too.2
Use these reports to spot a change in traffic or response time, then investigate with the logs and traces you configured. Check the time range, sampling, retention, and whether a caller could bypass this APIM instance before using the data to retire a version. APIM analytics and Application Insights answer different questions and have different coverage; neither can identify code reading a particular response field unless you deliberately collect data that reveals that behavior. Keep body logging off unless you have a specific, approved need, and set retention and access controls for any collected data.2
A rename, a rollback, and a graph that drained to zero
In this fictional example, Campux wants to rename price to priceExcTax. Removing the old field can break consumers, so Campux publishes and tests v2 while v1 remains available. The team tells consumers about the planned retirement and checks APIM analytics for calls by version. The graph shows that one marketplace still calls v1. Before the sunset, Campux contacts that team and confirms migration. The team checks that the dashboard's time range and coverage are suitable, then gives a final notice before retiring v1. The chart helps locate callers; it cannot prove which fields their code reads.
For a policy change, Campux creates a revision and protects its test URL. After testing, it makes the revision current and watches the configured telemetry. A latency increase prompts a rollback to the previous revision. The rollback changes APIM's active API revision; the team separately checks backend changes and side effects. Application Insights shows the gateway data that was configured and ingested, while backend telemetry helps locate delay beyond the gateway.
The desk, complete
Across these eight parts, you modeled an API, added policies and consumers, configured authentication, mapped network paths, and planned safe changes. Revisions give you a controlled test and release path; versions let consumers move to a breaking API shape; configured analytics and telemetry help you monitor both. You now have a practical way to make a change, test it, watch the result, and respond when it behaves differently than expected.
"Nobody uses that field — just delete it"
A backend engineer wants to remove a response field because “nobody uses it.” Removing a field can break callers, so keep v1 stable and test a new version without that field. APIM analytics may show which consumers call v1, but ordinary request telemetry does not tell you whether their code reads that specific response field. Confirm field usage with an approved, privacy-aware method, such as consumer confirmation or purpose-built telemetry that records only the needed signal. Check that coverage includes every route and caller, share a migration date, and give a final notice before retiring the old version. Do not log complete request or response bodies just to answer this question.
Continue with a supplied build
Follow the same fictional catalogue through this track. The supplied contract and worked checks let you practise without an Azure estate; the optional import/mock path makes real gateway requests. Each step states what it proves and what it does not.
Examination
Four drills, then two situations. The situations have no marking scheme — write your answer before you reveal the reasoning, or the exercise is worthless. Nothing is stored; this is between you and the page.
B — a rename is a breaking change, and breaking changes are versions. Anyone parsing the old field name fails the instant it disappears, so the change must be one callers choose (v2) while v1 keeps serving the people who haven't moved. A is the trap the whole part exists to defuse: promoting a breaking change as a revision makes it current for everyone at once, silently, and turns a rename into a simultaneous outage across every consumer. C is worse — an in-place edit has no previous and no undo, and "email the partners" is not a rollback plan. D ships the breakage first and reaches for the right tool only after the damage; the version is what prevents the complaint, not what answers it.
B — a revision gives you a previous API configuration to restore. You can make that revision current again if a release misbehaves. This restores APIM's API definition and policy; it does not undo database or backend side effects. A confuses revisions with versions: callers select versions, while APIM routes the normal URL to the current revision. A non-current revision also has a ;rev=N test URL, which callers can request if they know it. Protect or take the revision offline if it must stay private. C reverses the usual pattern: versions are typically used for breaking changes, while revisions are commonly used to test and release non-breaking changes. D is unrelated to revision behavior.
Options two, four, and five. The reports can show consumers, versions, traffic, response times, and failures when the relevant APIM analytics or diagnostics are enabled. Option five is carefully limited to calls visible in the selected report and time range; use that evidence as one input to a retirement plan, after checking coverage and consumer status. The first option is false: body logging is not an automatic, free, permanent record and can expose sensitive data. The third is false because whether a change breaks a caller depends on that caller's contract and code; the engineer must assess it.
# api change runbook
1. Non-breaking fixes ship as a new revision;
promote to current, watch App Insights.
2. If errors rise, make the prior revision
current again to roll back.
3. Breaking changes ship as a new revision too,
promoted at midnight to "minimise impact".
4. Retire an old version only after its call
count in analytics reaches zero.
Line three is the breaking change. Making that revision current routes normal API requests to the changed contract. Callers still using the old shape can fail, so publish a separate version and let consumers migrate. Line one describes the usual revision workflow; line two is a valid APIM rollback for the API definition and policy. Line four also needs careful interpretation: a zero count is useful evidence only if the report covers the relevant gateways, consumers, and period, and you have confirmed migrations. Never treat one chart as proof that no caller can return.
Separate the two claims, because they fail differently. The engineer has bundled a mechanism claim ("ship it as a revision") with an evidence claim ("nobody uses it"), and both need answering. Take the mechanism first: removing a field is a breaking change, and a revision promoted to current applies to everyone at once. So even if the field really is dead, shipping it as a revision is the wrong tool — it is a version, a v2 without the field that callers opt into, while v1 keeps serving anyone who hasn't moved. The versioning is not overhead; it is the thing that makes the removal survivable.
Check what the evidence can actually tell you. APIM analytics may identify who called v1 and how often, but ordinary request records do not show whether the caller's code reads legacyId from the response. Ask consumers to confirm, or add approved telemetry that records only the needed usage signal. Avoid logging full bodies just to answer this; that adds privacy, security, performance, and retention concerns.
Then plan the change. Publish v2 without the field, share a migration plan and end-of-support date, monitor all known routes, and confirm each consumer has moved. Check the report window and coverage, then send a final notice before retirement. A graph can support the decision; it cannot replace direct migration confirmation when the field usage is unknown.
Start by classifying the change. "Non-breaking updates are commonly released through revisions. I create a draft, protect its ;rev test URL, validate it, then make it current. If APIM behavior regresses, I can make the previous revision current again, while separately checking backend changes and side effects."
For breaking changes, publish a version. "I keep v1 available while v2 is tested and consumers migrate. I share a sunset plan, review call reports across all routes and time windows, contact remaining consumers, and confirm migration before shutdown. A report showing zero calls is one useful signal; it does not tell me whether client code reads a particular response field."
Use the right telemetry for each question. "I enable APIM diagnostics and built-in analytics deliberately, check sampling and retention, and protect collected data. APIM reports help me compare traffic, response times, and failures. To locate backend delay, I also need correlated backend telemetry. I check the selected time range and any paths that bypass APIM before using a trend to make an operational decision."
Five things worth carrying out of this part
- Every change is breaking or non-breaking, and that single question picks the tool. Get the sort wrong and the right-looking mechanism ships an outage.
- A revision is commonly used to test and release non-breaking changes. Protect its ;rev=N test URL; roll back APIM changes by restoring the prior revision.
- A version is for breaking change: a consumer-visible variant (path / header / query) that callers opt into, with v1 and v2 running side by side so nobody moves on your schedule.
- During deprecation, use analytics to find calls and coordinate migration. Check coverage and time range, contact consumers, and send a final notice before shutdown.
- Built-in analytics, configured APIM diagnostics, Azure Monitor, and Application Insights provide different views. Check sampling, retention, route coverage, and privacy settings before relying on a report.
- Microsoft's revision guide documents the ;rev=N URL, same-by-default security settings, taking revisions offline, making a revision current, and rolling back. ↩
- Microsoft's APIM observability guide compares built-in analytics, metrics, and tracing. The Application Insights integration guide explains diagnostic configuration, sampling, data volume, and performance impact. Configure and review these settings before relying on counts or collecting payloads. ↩
- Microsoft's versioning guide explains version sets and path, header, and query schemes. ↩
Version an API without breaking a client, and see what the gateway is doing in Application Insights.
Play the lesson above to stamp this class.