Comparison
Backward compatibilityvsHyrum's law
Backward compatibility
you add the field as optional so the clients that have never heard of it keep working unchanged.
The property that existing callers keep working against the new version. It is the constraint that governs every API change once you do not control all clients. The practical rules are small: add optional, never remove or rename, never narrow a type, never add a required field, never change the meaning of an existing value.
Full entry →Hyrum's law
you changed the order of a JSON response and a customer's integration broke, and nowhere did you promise an order.
With enough users, every observable behaviour of your system will be depended on by somebody, regardless of what you documented. Response ordering, timing, error message wording, the number of decimal places — all of it becomes contract by use. It is the reason internal-only rarely stays internal-only and the reason a deprecation plan is a negotiation about actual usage rather than about what the specification said.
Full entry →