All articles
ProductIntroducing API Genie, part 2

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

  1. 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.
  2. Window. Consumers migrate. The server emits both, accepts both.
  3. 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.

Andriy Mykulyak builds API Genie.LinkedInXcontact@apigenie.pl
Was this helpful?

Try API Genie on your own schema

Run it with Docker or download a binary for your platform.

Get API Genie