Aroma Store's v1 contract is practically closed: resources, methods, codes, representations and collections. And just as a contract is published, the real problem begins: the business changes and the API has to change with it, without breaking anyone. Aroma Mobile has versions installed on phones that nobody is going to update for months; SwiftShip has an integration written a year ago that works and that nobody wants to touch. This lesson teaches you to draw a precise line between changes you can make without warning and those you cannot, compares the five versioning strategies used in the industry, justifies Aroma Store's choice and designs the complete deprecation cycle, from the announcement to the shutdown.

1. Why versioning is a last resort
2. Backwards-compatible versus breaking changes
3. Table of changes to the Aroma Store API
4. Versioning strategies
5. Comparison and Aroma Store's decision
6. SemVer applied to APIs and its limits
7. Versions living side by side
8. Life cycle and deprecation
9. The Deprecation, Sunset and Warning headers
10. Strategies for not having to version

Publishing a v2 sounds like progress. In reality it is an invoice: two code bases to maintain, two sets of documentation, two test suites, two security surfaces, and a migration that has to be negotiated with every consumer. Well-known companies have spent a decade maintaining their v1 because switching it off turned out to be impossible.

That is why rule number one of versioning is: avoid needing it. Most changes can be made in a backwards-compatible way if the contract was designed with tolerance to change (02-01) and if you can draw a precise line between what breaks and what does not. That is exactly what the next section does.

The operational definition, and the only one that is any use:

A change is backwards-compatible if a client written against the previous contract, and behaving correctly, carries on working without touching a single line.

Notice the nuance "behaving correctly": a client that breaks because it iterated over the JSON's fields assuming there were exactly five is not your fault, as long as the documentation warned that new fields may appear. Hence the robustness principle and the tolerant reader from 02-01 are not soft advice: they are the condition that makes evolution without versioning possible.

• Adding is almost always safe (fields, endpoints, output enumeration values, optional parameters).
• Removing, renaming or restricting almost always breaks (fields, endpoints, accepted values, status codes).

This is what confuses people most, and it is worth thinking through slowly: adding a value to an enumeration is not the same thing in the response as in the request.

• On output (server responses): adding status: "returned" is a potentially breaking change for clients that do a switch with no default case. It is considered acceptable only because the documentation warns from day one that enumerations grow.
• On input (client requests): accepting a new value in roast is completely safe, because nobody was sending it before.

The mirror image, for the same reason inverted: relaxing an input validation is safe; tightening it breaks. If today you accept comments of 5,000 characters and tomorrow you limit them to 500, clients that were working stop working.

The last row points at a genuine grey area: fixing a bug can break whoever depended on the bug. It is documented in the changelog, it is announced, and in general it is considered a non-breaking change. But if the wrong behaviour had been there for two years, it may have become contract de facto: it has to be looked at case by case.

It is the most used in the industry: Twitter/X, GitHub (for years), Stripe in its base URL, almost every corporate API.

In favour: visible at a glance; it can be tested with a browser or with curl without headers; routing is trivial (a prefix); logs and metrics separate versions effortlessly; the documentation's examples are self-contained.

Against: REST purists object that the URI should identify the resource, not its format, and that /v1/coffees and /v2/coffees are "the same coffee" with two different URIs; on top of that it versions the whole API even when only one resource changes, and the _links clients have stored are pinned to a version.

In favour: the base URI is unique; it is easy to test; you can give it a default value.

Against: it gets mixed up with the business parameters (filters, sorting, pagination), it is easily lost when copying URLs, it complicates caching and it makes it ambiguous which version is served if the parameter is missing.

In favour: the URIs stay clean and stable; it allows granular versioning.

Against: invisible. You cannot paste a link into a ticket and expect it to reproduce the problem; testing in a browser is impossible without tooling; caches need Vary: Aroma-Version and many gateways ignore it; and you have to decide what happens if it is not sent.

It is the most correct option from REST's point of view: the version belongs to the representation, and the representation is negotiated with Accept (02-05). GitHub used it for years (application/vnd.github.v3+json).

In favour: theoretically impeccable; it uses a standard HTTP mechanism; it allows versioning resource by resource.

Against: the hardest to use. Nobody remembers the string by heart; curl requires an explicit header; many tools and generated clients handle it badly; and just like the custom header, it is invisible in the URL.

This is Stripe's style: each account is anchored to the version in force on the day it integrated, and the server applies chained transformations to adapt the current response to the shape expected on that date.

In favour: there are no traumatic jumps from v1 to v2; changes are introduced continuously; every consumer migrates when it wants to; it is the one that scales best on large public APIs.

Against: high complexity. It demands maintaining a well-tested chain of transformations and considerable engineering discipline. It is an excellent pattern for a company whose product is the API, and disproportionate for almost everyone else.

Aroma Store's decision: the version in the path (/v1).

The reasons, in order of weight:

1. Visibility and support. When SwiftShip raises an incident and pastes a URL, we will know exactly what they are talking about. With headers, half the tickets start with "which version were you using?".
2. Cost of implementation and operation. A path prefix is routed, deployed, measured and switched off with standard tooling. With four consumers and a small team, theoretical purity does not pay off.
3. Teaching and documentation. Every curl example in the documentation works copied and pasted, with no hidden headers.
4. Consistency with what has already been decided. The base URL with /v1 has been fixed since module 1 and published to the four consumers.

And the associated decisions, which are also contract:

• Only the major number is versioned: /v1, /v2. Never /v1.2. Minor changes are backwards-compatible by definition and need no new URL.
• The version is mandatory in the path. There is no https://api.aromastore.example/coffees without a version that "points to the latest": a client that does not choose a version ends up broken the day the latest one changes.
• All resources share a version. The whole API steps up at once, even if only orders change. It simplifies the reasoning at the cost of some granularity.

SemVer (semantic versioning) defines MAJOR.MINOR.PATCH:

Applied to an HTTP API, SemVer has three limits worth being clear about:

1. Only the major number appears in the URL. A consumer does not care whether it is using 1.4.2 or 1.7.0: the contract it sees is the same. Minor and patch live in the changelog, not in the path.
2. There is no "installation" to pin. With a library, the consumer decides when to upgrade; with a hosted API, the server upgrades for everyone at once. That is why minor changes have to be rigorously backwards-compatible: there is no going back for the client.
3. The major/minor boundary is negotiated. Adding an enumeration value on output (section 2.2) is, technically, potentially breaking; declaring it MAJOR would force you to publish a v2 every quarter. It is documented as expected and treated as MINOR with a prior announcement. Write that policy into the style guide, because it is the decision that prevents the most arguments.

Aroma Store therefore maintains two numberings: the URL version (v1) for the contract, and the internal semantic version (1.7.0) in the changelog and in OpenAPI's info.version field (02-08).

When v2 arrives, the two coexist for a while. The practical questions:

Two at most: the current one and the previous one under deprecation. Three live versions is a sign that the previous migration never finished, and the cost grows more than linearly: every security fix and every business change has to be applied to all of them.

The usual pattern, and the one Aroma Store will use in module 3: a single application with two presentation layers over shared business logic.

The key is not to duplicate the business logic. v1 is implemented as an adaptation layer over the current model: it renames fields, trims what did not exist, calculates what was removed. Duplicating the whole service guarantees that the two versions diverge in behaviour and that bugs appear which only happen on one of them.

When the transformation stops being possible —because the data model genuinely changed— that is the signal that v1 should be switched off, not that the system should be duplicated.

Every version goes through four phases:

Aroma Store's timetable, written into the documentation before publishing v1 —because withdrawal conditions are announced at the start, not when they have already become inconvenient:

A minimum of 12 months for external consumers such as SwiftShip. For our own clients (SPA, panel) the deadline can be shortened because we control the deployment, but not for Aroma Mobile: there are users who do not update the app in a year, and that is the consumer that really sets the timetable.

A deprecation that lives only in HTTP headers is a deprecation nobody reads. The complete package:

1. Headers on every response (section 9) — for the software.
2. A changelog with the date, the reason and a field-by-field migration guide — for the developer investigating.
3. A direct email to the technical leads of every identified consumer — for the human who decides.
4. A notice on the developer portal (05-06).
5. Segmented reminders: only to whoever is still using the old version, with their concrete usage data. A generic email gets ignored; "we recorded 12,400 calls from you to /v1 this month" does not.

Nothing gets switched off without data. You have to measure, by version and by consumer:

This requires identifying every consumer, which is achieved with each one's API key or token (04-03) and with the observability from 04-07. Without consumer identification there is no possible deprecation: only blind shutdowns.

When the date arrives, v1 responds:

410 Gone and not 404: the resource existed and has been deliberately removed (02-04). And v1 is not redirected to v2 with a 301: the contracts are different, so the client would receive a response with another shape and would fail confusingly. A clear error is better than a misleading success.

The standard lets you announce the withdrawal within the protocol itself, so that software can find out without reading an email.

An important detail that gets forgotten: these headers can be used without publishing a new version, on one specific resource or field. If Aroma Store is going to withdraw /v1/customers/{id}/preferences and replace it with something else, that particular endpoint can carry Deprecation and Sunset while the rest of v1 stays perfectly healthy.

And a practical recommendation for consumers, worth including in the documentation: log a warning in your logs when these headers arrive. It is the cheap way of finding out about a deprecation without depending on somebody reading the right email.

We come back to where we started: the best new version is the one you do not need. Five concrete techniques.

Add instead of changing. When a field has to be replaced, both coexist during the transition:

price is documented as deprecated, with a withdrawal date, and disappears in v2. It costs you duplicating one piece of data for a few months; it saves you a whole version.

This is the consumer's responsibility, and it has to be documented and repeated:

The second version survives the day status: "returned" turns up. A tolerant client is what turns "adding" into a safe operation, and that is why Aroma Store documents it as an integration requirement, not as advice.

A new behaviour is enabled first for one specific consumer, measured and then generalised. It lets you validate a doubtful change with the SPA (which we control) before exposing it to SwiftShip. Careful: a flag that stays forever is a version in disguise; every flag needs a withdrawal date.

Already designed in 02-05: expand and fields absorb a good share of change requests ("we need the customer's data inside the order") without touching the contract, because the generic mechanism was already in place.

If /coffees has to change radically, sometimes the right answer is not a complete v2 but a new resource with a name of its own (/catalogue, /products) that lives alongside the old, now deprecated, one. You pay with two names for similar concepts, and you get paid in not versioning the whole API for a single resource.

• Versioning out of habit. Publishing v2 because "it is time" doubles the cost without adding value. Version only when a breaking change is unavoidable.
• Believing that adding a field never breaks. That is true for tolerant clients; with strict schema validation on the client, it breaks. That is why you have to document that the API may add fields.
• Changing a field's meaning without changing its name. The worst possible change: it does not fail, it lies. priceEuros switching to cents multiplies prices by a hundred silently.
• Not versioning the error contract. Error codes are contract just as much as fields: renaming them breaks clients (02-04).
• Keeping three or four versions alive. It is a symptom, not a virtue: it means no migration was ever completed.
• Switching off with no data and no warning. Without per-consumer metrics and an announced deadline, the shutdown is a serious incident with your partner.
• Redirecting v1 to v2 with a 301. The contracts are different: the client will get a 200 with a shape it does not expect and will fail incomprehensibly.
• Tip: write the changelog from day one. It is the cheapest artefact and the one consumers are most grateful for (02-08).
• Tip: apply the "frozen client test". Faced with each change, ask yourself: would the version of Aroma Mobile installed a year ago still work? If the answer is no, it is breaking.

For each proposed change to Aroma Store's v1, state whether it is backwards-compatible or breaking and justify it. If it is breaking, propose an alternative that is not.

1. Adding averageRating and reviewCount to the coffee representation.
2. Renaming tastingNotes to tasteNotes.
3. Adding the returned status to orders.
4. Ceasing to return email in the customer representation for privacy reasons.
5. Accepting PATCH with application/json-patch+json, in addition to Merge Patch.
6. Changing totalEuros from 29.00 to "29.00" (a string) to avoid floating-point problems.
7. Making Idempotency-Key mandatory on POST /coffees/{id}/reviews.
8. Lowering the maximum limit from 100 to 50 because of performance problems.

Aroma Store needs to support several currencies. The current shape is:

And the desired one:

Design the complete migration: is it breaking? Can v2 be avoided? What is published and when? Which headers are sent and what is communicated to each of the four consumers?

Six months have passed since v2 was published and these are the v1 usage figures:

Decide whether v1 can be switched off in month 12 and draw up the action plan for each consumer.

Solution 1

Solution 2

Is it breaking? Yes, with no qualifications: priceEuros would disappear and change type (number → object). Any client that displays prices breaks, and in the worst case it displays [object Object].

Can v2 be avoided? Yes, with the field coexistence technique, and this is the right answer:

Phase 1 (month 0). price is added without removing anything:

A backwards-compatible change: old clients carry on reading priceEuros; new ones use price. As long as there are only euros, the two fields coexist without ambiguity. It is published in the changelog, priceEuros is documented as deprecated and the equivalence is explained.

Phase 2 (months 0-12). Responses with field-level headers and usage tracking:

You measure which consumers are still reading priceEuros —which in practice means asking them, because the server cannot see which fields the client uses: this is where fields= from 02-05 is useful as an indicator.

Phase 3. When the first non-euro currency appears, priceEuros stops being representable and that is when v2 is born, removing the old field. In other words: v2 is postponed until the business justifies it, it is not triggered by a change of shape.

Communication per consumer:

Solution 3

Verdict: it cannot be switched off in month 12 without prior work. There are two serious blockers and one minor one.

Revised plan: keep the deprecation date, but set the shutdown at month 12 conditional on two measurable milestones: (1) that Aroma Mobile v1 falls below 2% of total traffic, and (2) that SwiftShip confirms its migration in writing. Between months 9 and 12, monthly reminders with concrete figures; in month 11, v1 in read-only mode to force forgotten integrations into the open; and a one-hour shutdown rehearsal (brownout) in month 10, announced in advance, which is the most effective technique for flushing out the consumers nobody knew existed.

Versioning is expensive, so the real goal is to need it as little as possible. You now know how to draw a precise line between a backwards-compatible change and a breaking one —adding is safe, removing, renaming, restricting and changing types is not, with the key asymmetry between input and output— and you know the worst category of all: the silent change that does not fail but lies. You have compared the five versioning strategies and you know why Aroma Store versions in the path with /v1, prioritising visibility and operational cost over the REST purity of the media type. And you have the complete life cycle: two coexisting versions at most over shared business logic, twelve months of notice for external consumers, Deprecation and Sunset headers with Link to the successor and to the migration guide, per-consumer metrics so you know who to call, and a shutdown with 410 Gone instead of a misleading redirect.

With this, the v1 contract is complete and it also has an evolution policy. What is missing is the piece that makes it usable by other people: telling them about it. In the next and final lesson of the module, 02-08 API Documentation, we will see why documentation is part of the product, which kinds of document serve which reader, what each endpoint's reference must include, and what changes when the contract is written in a machine-readable format such as OpenAPI. We will close by taking stock of Aroma Store's complete contract and preparing for the jump to module 3, where it is finally implemented.