Ship a breaking change without breaking anyone
Andriy Mykulyak · · 7 min read
A pull request on the Carpet Express API renames the shipment’s reference to
merchantReference, in each request and response that carries a shipment, and drops the legacy
GET /rates/legacy. Both changes are right. Both break the clients that exist today, and
apigenie diff says so:
$ apigenie diff carpet-express.openapi.yaml pr/carpet-express.openapi.yaml
pr/carpet-express.openapi.yaml
866 7 breaking Removed operation GET /rates/legacy
1279 7 breaking Modified operation GET /jobs/{jobId}
1279 7 breaking Modified response code 200
841 7 non-breaking Modified operation POST /rates
841 7 non-breaking Request body changed
133 7 breaking Modified operation GET /shipments
133 7 breaking Modified response code 200
218 7 breaking Modified operation POST /shipments
218 7 breaking Request body changed
218 7 breaking Modified response code 201
218 7 breaking Modified response code 202
318 7 breaking Modified operation POST /shipments/imports
318 7 breaking Modified response code 202
301 7 breaking Modified operation POST /shipments/search
301 7 breaking Modified response code 200
418 7 breaking Modified operation GET /shipments/{shipmentId}
418 7 breaking Modified response code 200
457 7 breaking Modified operation PATCH /shipments/{shipmentId}
457 7 breaking Request body changed
457 7 breaking Modified response code 200
$ echo $?
1
The usual answers are “bump the major version” (and run two APIs for a year) or “just do it” (and
answer the support tickets). There is a third answer that database people have used for decades
and API people rarely do, because it is tedious by hand: expand, then contract.
apigenie evolve plan does the tedious part. It is experimental in 0.10.0, which means its options
and the layout of its plan can still change in a minor release.
Expand and contract, once
- Expand. Add the new shape next to the old one. Mark the old one deprecated with a sunset date. Nothing breaks: every old client still works, every new client can move.
- Window. Consumers migrate. The server emits both, accepts both.
- Contract. On or after the sunset date, remove the old shape.
The reason teams don’t do this is not that they disagree with it. It is that step 1 means
hand-editing the spec into a third document that is neither the old one nor the new one, getting
each deprecated: true, each x-sunset, each “now optional, later required” right, and then
convincing yourself it really is non-breaking.
Plan the change
Give it the document consumers use today and the document the pull request arrives at:
$ apigenie evolve plan carpet-express.openapi.yaml pr/carpet-express.openapi.yaml --window 90d --out evolve-out
apigenie evolve plan (experimental, outside the 1.0 compatibility promise)
Evolution of carpet-express.openapi.yaml to pr/carpet-express.openapi.yaml (today 2026-10-29, window 90d)
expand wave (version 2.5.0): ship now
remove-operation-quoteRateLegacy [remove-operation] deprecate GET /rates/legacy; sunset 2027-01-27
rename-request-property-FreightShipment-allOf-0-reference [rename-request-property] keep /components/schemas/FreightShipment/allOf/0/properties/reference (deprecated) next to /components/schemas/FreightShipment/allOf/0/properties/merchantReference; sunset 2027-01-27
rename-request-property-Job-result-oneOf-1-oneOf-0-allOf-1-parcels-items-reference [rename-request-property] keep /components/schemas/Job/properties/result/oneOf/1/oneOf/0/allOf/1/properties/parcels/items/properties/reference (deprecated) next to /components/schemas/Job/properties/result/oneOf/1/oneOf/0/allOf/1/properties/parcels/items/properties/merchantReference; sunset 2027-01-27
contract wave (version 2.6.0): not before 2027-01-27
remove-operation-quoteRateLegacy remove GET /rates/legacy
rename-request-property-FreightShipment-allOf-0-reference remove /components/schemas/FreightShipment/allOf/0/properties/reference
rename-request-property-Job-result-oneOf-1-oneOf-0-allOf-1-parcels-items-reference remove /components/schemas/Job/properties/result/oneOf/1/oneOf/0/allOf/1/properties/parcels/items/properties/reference
Server checklist:
- accept both reference and merchantReference until 2027-01-27 (rename-request-property-FreightShipment-allOf-0-reference)
- accept both reference and merchantReference until 2027-01-27 (rename-request-property-Job-result-oneOf-1-oneOf-0-allOf-1-parcels-items-reference)
Checks:
expand-non-breaking: ok
contract-scheduled-only: ok
contract-equals-target: ok
Written:
evolve-out/plan.yaml
evolve-out/1-expand.yaml
evolve-out/2-contract.yaml
Twenty breaking lines became three units: the removed operation, and the renamed property seen
through the two schemas that carry it (the unit is named after the first place the differ reported
the property; sites in plan.yaml lists the others). Three files land in evolve-out/:
| File | What it is | When to ship it |
|---|---|---|
1-expand.yaml |
The target document with each old element kept next to its replacement, deprecated: true and x-sunset |
now |
2-contract.yaml |
The target document | on or after the sunset date |
plan.yaml |
The waves, the units, the residue, the server notes |
In the expand wave, the old property sits next to the new one with its sunset:
reference:
type: string
description: Your order or delivery number.
maxLength: 64
deprecated: true
x-sunset: 2027-01-27
How it knew it was a rename
The differ sees a removed property and an added one. The planner pairs them when the removed and
the added member have the same schema after following $refs and ignoring descriptions and
examples; plan.yaml records the pairing with detected: true. For reference and
merchantReference (both string, maxLength: 64) that is enough. When it isn’t, you tell it:
# hints.yaml
renames:
- from: /components/schemas/ShipmentCommon/properties/reference
to: /components/schemas/ShipmentCommon/properties/merchantReference
window: 12w
reason: Align field names with the merchant portal
$ apigenie evolve plan carpet-express.openapi.yaml pr/carpet-express.openapi.yaml --hints hints.yaml --out evolve-out
apigenie evolve plan (experimental, outside the 1.0 compatibility promise)
Evolution of carpet-express.openapi.yaml to pr/carpet-express.openapi.yaml (today 2026-10-29, window 12w)
expand wave (version 2.5.0): ship now
remove-operation-quoteRateLegacy [remove-operation] deprecate GET /rates/legacy; sunset 2027-01-21
reason: Align field names with the merchant portal
The reason travels into the plan and the report, so the person who reads plan.yaml in February
knows why the field moved.
The recipes, and what has none
Each breaking change becomes a unit with a recipe, and the recipes are the moves a careful API owner makes by hand: an operation that goes stays deprecated with its sunset, then is removed; a renamed property keeps both names, then loses the old one; a request property that becomes required is optional first. The reference lists them.
Some breaking changes have no safe recipe: a changed type or format, a new security requirement,
a replaced server. Those are residue. Change transitDays from an integer to a string in the
same pull request, and the plan says so instead of pretending:
$ apigenie evolve plan carpet-express.openapi.yaml pr/residue.yaml --window 90d --out evolve-residue
apigenie evolve plan (experimental, outside the 1.0 compatibility promise)
Evolution of carpet-express.openapi.yaml to pr/residue.yaml (today 2026-10-29, window 90d)
expand wave (version 2.5.0): ship now
contract wave (version 3.0.0): not before 2027-01-27
Residue (needs a major version or a new resource):
residue-1 Added schema.type[0] at /components/schemas/Rate/properties/transitDays/type/0
a changed type or format has no parallel shape; add a property with the new type next to the old one
residue-2 Removed schema.format at /components/schemas/Rate/properties/transitDays/format
a changed type or format has no parallel shape; add a property with the new type next to the old one
$ echo $?
1
The files are still written, the contract wave becomes a major version, and the exit status is 1 until the residue is handled: a new property with the new type next to the old one, or a new resource.
Proved, not promised
Before anything is written, the planner runs diff three times, with your configuration, and
reports the checks you saw above. You can run the proof yourself at any time, which is the point
of writing the waves as plain documents:
$ apigenie diff carpet-express.openapi.yaml evolve-out/1-expand.yaml
evolve-out/1-expand.yaml
1352 7 non-breaking Modified operation GET /jobs/{jobId}
1352 7 non-breaking Modified response code 200
887 7 non-breaking Modified operation POST /rates
887 7 non-breaking Request body changed
1453 7 non-functional Modified operation GET /rates/legacy
119 7 non-breaking Modified operation GET /shipments
119 7 non-breaking Modified response code 200
209 7 non-breaking Modified operation POST /shipments
209 7 non-breaking Request body changed
209 7 non-breaking Modified response code 201
209 7 non-breaking Modified response code 202
321 7 non-breaking Modified operation POST /shipments/imports
321 7 non-breaking Modified response code 202
303 7 non-breaking Modified operation POST /shipments/search
303 7 non-breaking Modified response code 200
436 7 non-breaking Modified operation GET /shipments/{shipmentId}
436 7 non-breaking Modified response code 200
480 7 non-breaking Modified operation PATCH /shipments/{shipmentId}
480 7 non-breaking Request body changed
480 7 non-breaking Modified response code 200
$ echo $?
0
The same twenty lines, each one non-breaking. The contract wave is breaking today and
non-breaking once the sunset has passed, because diff knows the sunset dates:
$ apigenie diff evolve-out/1-expand.yaml evolve-out/2-contract.yaml | head -n 2
evolve-out/2-contract.yaml
1453 7 breaking Removed operation GET /rates/legacy
$ apigenie diff evolve-out/1-expand.yaml evolve-out/2-contract.yaml --today 2027-01-27 | head -n 2
evolve-out/2-contract.yaml
1453 7 non-breaking Removed operation GET /rates/legacy
A CI job with --today is the calendar entry that says when 2-contract.yaml may ship.
The server checklist
A document can say that both reference and merchantReference exist. Only the implementation
can emit both. Each unit that needs it carries a server note, and the report prints them as a
checklist. Put the checklist in the ticket. A plan whose server doesn’t follow its notes is a lie
the documents can’t catch.
What it does not do
The recipes cover OpenAPI documents; AsyncAPI, GraphQL and Protobuf have no planner yet. The plan is written once and not tracked: there is no command that tells you, in January, which units are past their sunset. And a change with residue is still yours to design. What it does is the part nobody did: write the intermediate document, and prove it.
Try it
curl -sSL https://api-genie.dev/examples/carpet-express.tar.gz | tar xz
cd carpet-express
apigenie evolve plan carpet-express.openapi.yaml pr/carpet-express.openapi.yaml --window 90d --out evolve-out
cat evolve-out/plan.yaml
Next week, the contract meets the traffic: The traffic you already have is the contract test.