Hyrum's Law
With enough users, every observable behaviour of your API will be depended on by somebody.
“With a sufficient number of users of an API… all observable behaviors of your system will be depended on by somebody.”
To an executive
Once many customers or partners rely on a product, even unintended behaviour becomes a promise. Changes then carry real cost and risk, so plan them carefully.
To an engineer
Assume consumers depend on everything observable, such as ordering, timing, error text and defaults. Treat changes to any of these as potentially breaking, and roll them out gradually.
The idea
Hyrum Wright, an engineer at Google, put it like this: with a sufficient number of users of an API, it does not matter what you promise in the contract; all observable behaviours of your system will be depended on by somebody. Titus Winters gave it the name.
The real contract is not what you document. It is everything consumers can observe: ordering, timing, error messages, default values, even bugs. The more consumers you have, the more any change becomes a breaking change for someone. Scale turns implementation details into commitments.
Why it works
Consumers code against what they see. Developers test against real responses, not the specification. If results always come back sorted, someone will rely on the sort.
Probability grows with users. Any one undocumented behaviour is unlikely to be relied on by a given consumer, but with enough consumers it becomes almost certain.
Breakage lands on the provider. When a change breaks a consumer, it does not matter that the behaviour was undocumented; the provider still has an incident and a rollback.
Where it applies
- Public and internal platform APIs, especially those with many teams as consumers.
- Shared libraries and SDKs, where internal classes and side effects leak to users.
- Event streams and data feeds, where field order, formats and timing become implicit contracts.
- Migrations and re-platforming, where the new system must reproduce behaviours nobody wrote down.
How to apply
- Minimise the observable surface. Expose as little as you can: fewer fields, fewer options, fewer details in error messages.
- Randomise what you will not promise. Shuffle unordered results or vary timing in test environments so nobody can come to depend on them.
- Know your consumers. Use consumer-driven contract tests and usage telemetry to see what is really relied on.
- Plan for change. Version deliberately, publish a deprecation policy, and give consumers a migration path before you break anything.
Example scenario
A platform team optimised a list endpoint, and as a side effect its results stopped coming back in creation order. Nothing in the documentation promised any ordering. A downstream finance report took the first and last records as the start and end of a period, and silently produced wrong totals for a month before anyone noticed.
After the incident, the team made ordering explicit with a documented sort parameter and began returning unsorted results in a random order in test environments. Consumer contract tests were added for the finance report. Two other hidden dependencies on ordering surfaced in testing rather than in production.
Questions to ask
- What observable behaviour are we promising without meaning to — ordering, timing, error text?
- If we changed this tomorrow, how would we find out who depends on it?
- Can we hide or randomise details we don't want to commit to before anyone relies on them?
When not to use it
- APIs with one or two consumers you control, where you can simply change both sides together.
- Throwaway prototypes, where nobody will depend on the system for long.
How it misleads you
Freezing everything forever out of fear. Hyrum's Law describes a cost of change, not a ban on it. Plan for controlled breaking changes with versioning, deprecation windows and migration paths, and accept that some consumers will need help to move.
In the wild
Further reading
Last reviewed · Suggest an improvement