APIs for Product Managers
Versioning and Backward Compatibility: The Promise You Cannot Break
Fig 3.1 — The versioning decision every API change should pass through
"We'll just add a field" is the sentence that has caused more production incidents than almost any other in API product management.
Not all changes are equal. Learn this distinction and you can catch most breaking-change disasters before they ship.
Change type | Example | Breaking? |
|---|---|---|
Add a new optional field to a response | Adding loyalty_tier to a customer object | Usually safe |
Add a new optional parameter to a request | A new filter option that defaults to "off" | Usually safe |
Remove a field | Removing legacy_status | Breaking |
Rename a field | cust_id → customer_id | Breaking |
Change a field's type or format | A date string changes from MM/DD/YYYY to ISO 8601 | Breaking, even though it "looks like an improvement" |
Make an optional parameter required | A previously optional region becomes mandatory | Breaking |
Change default behavior | An endpoint that used to return all records now paginates by default | Breaking, even with zero code changes on your end |
That last row is the one that surprises people most. You didn't touch the response shape at all — you changed a default, and it silently broke every caller who relied on the old default without ever explicitly requesting the new behavior. This is the API equivalent of a leaky data split from a training-data project: the danger isn't in what you changed, it's in what someone else was implicitly depending on that you never wrote down.
THE TWO SURVIVAL STRATEGIES
Additive-only evolution. Never remove or repurpose a field, ever. Only add. This keeps a single version alive indefinitely but accumulates cruft over years.
Explicit versioning. Ship breaking changes only inside a new version (/v2/customers alongside /v1/customers), give existing integrations a long, clearly communicated deprecation window, and never silently rewrite behavior on a version a caller is actively depending on.
Most mature API products do both: additive changes ship into the current version freely; anything breaking waits for the next major version and a real migration plan.
YOUR MOVE THIS WEEK
Look at your last five changes to a public or partner-facing API. Classify each honestly using the table above. If any were breaking and shipped without a version bump or a communicated migration window, that's not a hypothetical risk — go find out who it already broke.