Change Example: Five Changes, and Which Ones Break a Client

Adding a field, renaming one, making one required, changing a default and adding an endpoint; predict, then see.

The breaking-change test is clearest applied to five changes proposed for one orders API in the same release. For each, predict whether an existing client, which reads customerName and total, sends POST /orders without a currency, and lists orders without a page size, keeps working. The trace shows what that client sees. The requests and results are illustrative.

One existing client against each of the five changes

InputA client that reads customerName and total, posts orders without currency, and lists without a page size

Add a field
1. Response gains estimatedDelivery
2. Client ignores it
3. Workssafe
An optional field added to a response; a tolerant client never looks at it.
Rename a field
1. customerName becomes buyerName
2. Client reads a missing field
3. Failsbreaks
The client shows a blank name or throws, depending on its language.
Require a field
1. currency becomes required on POST /orders
2. Client's request has no currency
3. Fails with 422breaks
A request that was valid yesterday is refused today.
Change a default
1. Default page size drops from 50 to 20
2. Client receives 20 orders
3. Wrong, silentlybreaks
Nothing errors, so the client shows a short list and nobody notices for weeks.
Add an endpoint
1. New GET /orders/{id}/invoice
2. Client never calls it
3. Workssafe
A new path changes nothing the client already does.

ResultTwo of five changes are safe. Three break the client, and one of those breaks it without an error.

What decided each. The safe changes only added things the client never asked for. The rename removed something it read, the required field refused something it sent, and the default changed a result it relied on without saying so.

The silent one is the worst. A 422 shows up in logs the same day. A shorter list shows up as a support ticket weeks later, after the client's users have acted on missing data.

What the team should do. Ship the field and the endpoint now. Rename with expand and contract, keep currency optional with a documented default, and keep the page size at 50 unless the change goes into a new version.

← → move through sections and cards