Card 03/ 09
The Tolerant Reader: Ignore What You Do Not Know
A client that ignores unknown fields survives most changes; one that rejects them breaks on the first.
A tolerant reader is a client that reads only the fields it needs and ignores everything else in a response. Martin Fowler named the pattern: be strict in what you send, tolerant in what you accept. It is the client's half of evolving an API, because an added field is only a safe change for clients that do not reject what they do not recognise.
Strict clientbreaks on an addition
The deserialiser is set to fail on unknown properties, or the client validates responses against a schema with additionalProperties: false. The new estimatedDelivery field makes every order fail to parse, and the app shows an error.
Tolerant clientcarries on
The client maps id, customerName and total and ignores the rest. estimatedDelivery is skipped, and the app works exactly as before.
What a tolerant reader does.
- Ignores fields it does not use, rather than failing on them.
- Reads only the fields it needs, so a change elsewhere in the response cannot touch it.
- Treats a missing optional field as absent rather than as an error.
- Handles unknown values in a set it does not control, such as a status, with a default case.
Strict where it matters. Tolerance applies to reading responses. Requests the client sends should still match the contract exactly, and the server should still validate requests strictly, because that is where unknown fields are a risk rather than a convenience.
Settings decide it. Many JSON libraries choose for the developer. Jackson, a common Java library, fails on unknown properties by default unless configured otherwise, and some generated clients validate every response. Check the default of whatever the client uses.
So write clients that read what they need and ignore the rest, and tell the API's clients to do the same.
← → move through sections and cards