CSE Roadmap

Core tier · about 3 hours · 9 parts

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 /products to /fancy-products, or making an optional query parameter required, breaks old callers.
  • At the message: changing the type of category from 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:

  1. Release v2 next to v1.
  2. Tell callers, with a date for the end of v1.
  3. Watch the count of v1 calls. Contact the callers that remain.
  4. Switch off v1 only 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?