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 non-breaking changes. A parallel copy of the API you edit and test, then make current in one move — and roll back just as fast if it misbehaves. Consumers are not asked to do anything; the change simply becomes live.
- 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
- Not a flag day but a campaign: announce, give a date, watch the analytics for who is still on the old version, and retire it only when the traffic has actually moved — never before.
- Observability
- Application Insights and the built-in analytics — the instruments that tell you who is calling what, which version they are on, and what is slow, so a change is a measured decision rather than a hope.
Revisions — change you can take back
A revision is a parallel copy of an API that you can edit and test without touching what consumers currently hit. At any moment exactly one revision is current — the one live traffic flows to — and the others sit alongside it, reachable for testing but not serving the public. You make a change on a new revision, try it against the non-current revision's URL, and when you are satisfied you promote it to current in a single action. Consumers are asked to do nothing: their calls were going to the API, and the API's current revision quietly became the new one.1
The property that makes revisions worth their weight is rollback. Because the previous revision still exists, "make it current again" is one move, not a redeploy — the same instinct as a blue-green swap from the release classes. Ship a non-breaking change at nine, watch the error rate tick up at nine-fifteen, and make the old revision current again by nine-sixteen; the partners never write in. That is the whole reason you do not just edit the live API in place: an in-place edit has no previous, and a change with no previous is a change with no undo.
A change with no previous is a change with no undo.
Versions — change the caller chooses
When the change would break existing callers, a revision is exactly the wrong tool — promoting it to current breaks everyone at once, silently. That is what a version is for. A version is a separate, consumer-visible variant of the API, selected by the caller through a scheme you choose: a path segment (/v2/catalog), a header, or a query parameter. The property that matters: v1 and v2 run side by side: the partner still calling v1 keeps working, the partner ready for v2 opts in, and nobody is forced to change their code on a date you picked.
| Revision | Version | |
|---|---|---|
| Use for | Non-breaking change | Breaking change |
| Consumer visible? | No — they do nothing | Yes — they choose it |
| 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 turn the ugliest moment in an API's life — the breaking change — into a deprecation campaign instead of a flag day. You publish v2, announce v1's sunset date, and then you watch: the analytics show who is still calling v1, and you retire it only when that traffic has actually drained, chasing the last stragglers by name if you have to. The failure mode is deleting v1 on the calendar date while a partner is still on it — a breaking change dressed up as a schedule. The rule that keeps you employed: you retire a version when the traffic leaves, not when the date arrives.
Observability — seeing before you are told
Every decision above — is this change safe to promote, has v1's traffic drained, which operation got slow — is a guess without data. APIM's Application Insights integration (Class 30, arriving where it was always headed) is where the data lives: request telemetry for every call — which API, which operation, which version, the response code, the latency — plus distributed traces that follow a request from the gateway into the backend, so a slow call can be blamed on the right hop rather than the nearest one. On top of that sits APIM's built-in analytics: dashboards of top APIs, top consumers, response times, and failures, answering "who is calling what, and what is slow" without your writing a query.
This is the instrument panel that makes the rest of the track honest. It tells you a partner's key is being hammered before they complain (38d, 38e); it shows a spike of 401s the moment a token misconfiguration lands (38f); it confirms the old backend address went dark after the network change (38g); and it is the ground truth of a deprecation — the graph of v1 calls trending to zero is the only thing that makes retiring v1 safe. An API you cannot see is an API you are flying blind; the gateway's great quiet advantage is that every call already passes through one place, so one place can watch them all.2
A rename, a rollback, and a graph that drained to zero
Campux needs to rename price to priceExcTax in the catalog response — a clean break for anyone parsing the old field. They do not touch v1. They publish /v2/catalog with the new shape, announce a six-month sunset for v1, and watch Application Insights: the two marketplaces migrate within weeks, but the regional chain's traffic stubbornly stays on v1. Because the analytics name the laggard, the sunset is a phone call, not a surprise outage — and v1 is retired only after its call count reaches zero, three weeks past the original date, because the traffic, not the calendar, decides.
The revision half of the story happens the same quarter. A non-breaking fix to the stock-lookup policy ships as a new revision at nine in the morning; by nine-twelve the App Insights latency chart shows the operation has doubled its response time under a caching bug. The engineer makes the previous revision current again — one action — and the graph settles by nine-fourteen. No partner noticed, because the change that had a previous also had an undo. The postmortem is one line: we shipped what we could take back, and we watched the instrument that told us to.
The desk, complete
The front desk is finished. Across eight parts it learned to model an API (38c), to run behaviour on every request (38d), to name and enrol the consumers who call it (38e), to prove who they are on both sides of the door (38f), to sit on the wire as the only road in (38g), and now to change without breaking them and to watch itself while it does. That last pair is what separates an API that is launched from an API that is operated: versions and revisions let it evolve, observability lets it evolve on evidence. You can now stand in front of an interviewer, draw the gateway, and defend every box — which is, after all, the whole point of the desk.
"Nobody uses that field — just delete it"
A backend engineer wants to remove a response field they are sure is dead weight, and proposes shipping it as a quick revision this afternoon. Two things stop you. First, that is a breaking change — anyone parsing that field fails the moment it vanishes — so it belongs in a new version, not a revision promoted under everyone's feet. Second, "nobody uses it" is a claim you can check: you open Application Insights, filter to that field's operation, and look. If it is genuinely zero across a full billing cycle, you have evidence, not a hunch; if it is not, you have just saved a partner's afternoon and your own reputation. The move is the same either way — publish v2 without the field, announce a sunset, watch the v1 graph — but the instrument is what turns "I think it's safe" into "I can see that it is."
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 keeps a previous, and a previous is an undo. You promote a non-breaking change to current, watch the instruments, and if the error rate ticks up you make the prior revision current again in a single action — the same blue-green swap instinct from the release classes. An in-place edit has no previous to return to, which is exactly why you do not do it. A confuses revisions with versions: consumers choose versions; revisions are chosen by you (one is current at a time). C is backwards — revisions are the tool for non-breaking change; a breaking change needs a version. D invents a capability revisions do not have; they are about change management, not scale.
What's slow, who's calling what, and whether v1 has drained. Those are exactly the questions the instrument panel exists for — request telemetry and traces localise a slow hop, analytics rank consumers and APIs, and the v1 traffic graph is the ground truth that makes a deprecation safe. The two rejects are seductive overreaches. Telemetry is sampled and retained for a cost, not a perfect, free, forever record of every body — believing otherwise is how you both blow a budget and trust a number that isn't complete. And nothing decides breaking-vs-non-breaking for you; that is an engineering judgement about your consumers' code, and the analytics only tell you who would be affected, not whether the change is safe to make.
# 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 — and "at midnight to minimise impact" is the tell that someone knows it will hurt. A revision becomes current for everyone; if the change is breaking, promoting it breaks every consumer simultaneously, and doing it at midnight only means they discover it at breakfast. Breaking changes are versions — a parallel v2 the caller opts into while v1 keeps serving. The distractors are the runbook working: non-breaking changes are the correct use of revisions (A is wrong), rollback by making the prior revision current is precisely how revisions earn their keep (B is wrong), and retiring a version only when its traffic reaches zero is the whole discipline of deprecation — retiring on the calendar date regardless of traffic (D) is the exact mistake that turns a sunset into an outage. Move line three to a version and the runbook is sound.
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.
Then turn "nobody uses it" from a belief into a measurement. Concede that they might be right — and say that is exactly why we look rather than guess. Open Application Insights, filter to the operations that return legacyId, and read the traffic over a full billing cycle. If it is genuinely zero, we now have evidence to put in the deprecation notice; if it is not, we have just avoided breaking a partner who would have found out in production. The instrument is cheap; the wrong guess is a partner's outage and an awkward call.
Close on the workflow that satisfies the real goal. The engineer wants the field gone with minimal ceremony, and there is a clean path to exactly that: publish v2 without the field, announce a sunset date, watch the v1 graph, and retire v1 when its traffic reaches zero — not on the calendar, on the evidence. That is faster than an incident and slower than a mistake, which is the correct speed. We don't remove fields on a hunch; we remove them on a graph that reached zero.
Open with the sort, because every good answer here starts by classifying the change. "Every change is either breaking or non-breaking, and that single question picks the tool. Non-breaking — a new optional field, a bug fix, a policy tweak — ships as a revision: I edit a parallel copy, test it, promote it to current, and if the instruments turn bad I make the previous revision current again in one move. Nobody has to do anything, and every change has an undo." Leading with the taxonomy shows you have a system, not a bag of features.
Then handle the hard half without flinching. "Breaking changes — removing a field, changing a type — are versions. I publish v2 alongside v1, callers opt in by path or header, and the two run in parallel so nobody is forced onto my schedule. Retiring v1 is a campaign, not a flag day: announce a sunset, then watch who's still calling it and chase the stragglers, and only delete it when the traffic has actually drained. I retire a version when the traffic leaves, not when the date arrives." That last line is the sentence that tells the interviewer you have actually run a deprecation.
Close by making observability the thing that closes the loop. "None of that is safe blind, so Application Insights is wired in from day one: request telemetry and traces tell me which operation is slow and whether it's the gateway or the backend, and the analytics tell me who's calling what and which version. Health isn't a feeling — it's the error rate after a revision promotion, the latency percentiles per operation, and the v1 graph trending to zero before I retire it. The gateway's quiet advantage is that every call already passes through one place, so one place can watch them all." Ending on "I decide on evidence, not hope" is the senior note the whole question is listening for.
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 for non-breaking change: a parallel copy you promote to current and can roll back by making the prior revision current again. A change with no previous is a change with no undo.
- 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.
- Deprecation is a campaign, not a flag day. Announce a sunset, watch the analytics, and retire a version when its traffic reaches zero — not when the calendar date arrives.
- Application Insights and built-in analytics close every loop: which operation is slow, who calls what and which version, and whether v1 has drained. An API you cannot see is one you are flying blind.
- A revision has a subtlety worth knowing so it doesn't surprise you: non-current revisions are individually addressable — the gateway exposes them at a revision-qualified path (a ;rev=N suffix) so you can test one before promoting it — and promoting a revision to current is what actually swaps live traffic. Do not confuse "a revision exists" with "consumers can reach it": until you make it current, the public still hits the old one, which is exactly the safety the mechanism is for. ↩
- Treat the observability numbers with the same honesty this bootcamp asks of its own: Application Insights telemetry is typically sampled to control cost and volume, so the counts you read are representative, not a perfect census, and a rare error can hide below the sampling rate. That does not make the panel untrustworthy — the direction and the shape of the traffic are reliable, and the v1-drained-to-zero signal is sound — but before you retire a version on a "zero," confirm the sampling and retention settings so the zero means "no calls," not "no calls we happened to sample." ↩