Card 01/ 09
Breaking and Non-Breaking Changes
A change breaks an API when a client that worked yesterday fails today without changing a line.
A breaking change is one that makes an existing, correctly written client fail without that client changing anything. The test is about clients, not about the server's code: a large refactor that keeps every request and response the same breaks nothing, and renaming one field breaks every client that reads it. Removing, renaming, retyping and tightening break; adding something optional usually does not.
| Change | Breaking | Why |
|---|---|---|
| Remove a response field | Yes | Clients reading it get nothing |
| Rename a field | Yes | It is a removal and an addition at once |
| Change a field's type, such as a number to a string | Yes | Clients parse the old type |
| Make an optional request field required | Yes | Requests that left it out are now refused |
| Tighten validation, such as a shorter maximum length | Yes | Requests that passed now fail |
| Change a default, such as page size | Yes | Clients relying on the old value get different results |
| Change a URL or a status code | Yes | Routing and handling code depend on both |
| Add an optional response field | No, for a tolerant client | Clients that ignore unknown fields carry on |
| Add an optional request field or a new endpoint | No | Existing requests are unchanged |
| Loosen validation | No | Requests that passed still pass |
The asymmetry. What the API accepts can grow, and what it returns can grow, but nothing a client already depends on can shrink or change meaning. Requests can become more permissive; responses can gain fields but not lose them.
Behaviour counts too. A change to what an endpoint does, with the same shape, can break a client as surely as a renamed field: a list that used to be sorted by date and now is not, or a DELETE that used to be immediate and is now delayed.
Additive changes need tolerant clients. "No" in the table assumes the client ignores what it does not recognise. The topic's card on the tolerant reader shows what happens when it does not.
So before each release, ask of every change whether a client written yesterday would notice it.
← → move through sections and cards