Part 7 of 9 · 3 min read
Change without breakage
Which changes break old callers, and three ways to carry a version.
Think of a power socket. A new plug design may be better, but millions of old plugs exist. A good change fits the old plugs too, and a breaking change needs a new socket next to the old one.
APIs must change as the product grows. Some callers, such as old mobile apps, cannot be updated on the same day.
Backward compatible
A change is backward compatible if callers written for the old version still work. A change is forward compatible if old code can read data written by newer code.
Example: adding an optional field nickname to a reply is backward compatible. Old clients ignore it.
The book "Understanding Distributed Systems" separates changes at two levels.
- At the endpoint: renaming
/productsto/fancy-products, or making an optional query parameter required, breaks old callers. - At the message: changing the type of
categoryfrom a string to a number breaks the old parsing code.
Safe changes usually add. Unsafe changes remove, rename or change a type.
| Change | Safe? |
|---|---|
| Add an optional field to a reply | Yes |
| Add a new endpoint | Yes |
| Add an optional query parameter | Yes |
| Remove a field | No |
| Rename a field | No |
| Change a field type | No |
| Make an optional parameter required | No |
For binary formats the rule is the same, with sharper details. In Protocol Buffers each field has a numbered tag. The book "Designing Data-Intensive Applications" explains that a field may be renamed but its tag number must never change. New fields get new tag numbers and must be optional or have a default, so that new code can read old data. A removed field's number must not be used again. Old code that meets an unknown tag skips that field, which keeps forward compatibility.
When a breaking change is truly needed, the API gets a version. The book lists three places to carry it.
| Place | Example |
|---|---|
| In the URL | /v1/products |
| In a custom header | Accept-Version: v1 |
| In the content type | Accept: application/vnd.example.v1+json |
The URL form is the easiest to see, test and cache. The others keep URLs clean.
A plan for a breaking change:
- Release
v2next tov1. - Tell callers, with a date for the end of
v1. - Watch the count of
v1calls. Contact the callers that remain. - Switch off
v1only when the count is near zero.
The book also advises preferring backward compatible changes unless there is a strong reason, and running a tool in the build pipeline that compares the old and new API descriptions and flags breaking differences. Such descriptions are written in an interface description language such as OpenAPI, which lists endpoints, methods, status codes and message shapes. The same description can generate documentation and client code.
Common mistake
Treating a new required field as a small change. Every old client that does not send it starts to fail. Make new fields optional with a sensible default.
Check yourself:
- Which is safe: removing a field, or adding an optional one?
- Why does a numbered tag in Protocol Buffers help old and new code to coexist?