Hyrum’s Law warns API teams that clients may depend on any behavior they can observe—not just the behavior promised in the documentation. The larger and more varied an API’s user base becomes, the harder it is to know which seemingly minor changes are safe.
What is Hyrum’s Law?
Hyrum Wright’s canonical wording is: “With a sufficient number of users of an API, it does not matter what you promise in the contract: all observable behaviors of your system will be depended on by somebody.” The statement appears in Software Engineering at Google: Lessons Learned from Programming Over Time.
The key idea is that an API’s practical interface can be broader than its documented contract. The contract describes intended behavior; clients can also observe implementation details and build assumptions around them. Those assumptions may become dependencies even when the API team never meant to support them.
“A sufficient number” is qualitative: Hyrum’s Law gives no universal user count or probability of breakage. It is an engineering observation about risk, not a mathematical theorem saying that every behavior has a dependent or that APIs can never change.
Recommended Free Tools
#1 Best Overall
- API Design Patterns
- ABIS BOOK
- Manning Publications
Why do undocumented behaviors become dependencies?
Clients often rely on whatever makes their own work predictable. If a response happens to arrive in a consistent order, an error includes a particular phrase, or a default behaves in a useful way, a client may encode that assumption in its code or tests. The dependency exists whether or not the API documentation mentions it.
Wright described encountering unexpected failures from small changes to details such as line numbers, comments, and log messages. For APIs, potentially observable behavior includes:
Rank #2
- Ordering of fields or returned items.
- Timing and latency patterns.
- Error codes, messages, and response shapes.
- Serialization details and formatting.
- Limits, defaults, and how strictly inputs are validated.
- Bugs or other implementation quirks that clients have learned to accommodate.
Google’s SRE migration guidance therefore treats migration sequencing as relevant not only to documented features, but also to accidental features, implementation idiosyncrasies, and bugs.
What does Hyrum’s Law mean for API changes?
A change can be correct against the written contract and still break a client that depends on an observable detail outside it. The risk grows with the size and diversity of the consumer population, how independently clients upgrade, and how costly it is to coordinate their migration.
This does not make change impossible. It means the API team should treat compatibility as a decision informed by evidence, not assume that an undocumented behavior is unused. Documentation remains important because it states the intended interface, but it cannot by itself reveal every real-world dependency.
How can API teams assess compatibility risk?
Before changing a behavior, assess both the possible impact and the quality of the evidence available. Useful questions include:
- Who uses the API? Identify consumers and consider how many there are, how diverse their uses are, and whether they upgrade independently.
- What can they observe? Separate documented promises from visible details such as response ordering, errors, timing, defaults, and leniency.
- What evidence exists? Review request, response, error, latency, and version patterns. Check whether compatibility or consumer-driven tests cover the behaviors that matter most.
- How difficult is migration? Consider the cost of coordinating clients and the consequences if some do not upgrade promptly.
- Can the change be controlled? Check whether the team can stage rollout, communicate warnings, measure adoption, and roll back if clients fail.
Telemetry shows observed use, not every latent dependency: a client may rely on a behavior without exercising it during the observation period. Tests can reveal assumptions represented in their coverage, but they cannot prove that no other client depends on the behavior.
How should teams change an API safely?
- Inventory consumers and usage. Establish which clients use the affected area and inspect real request, response, error, latency, and version patterns.
- Define the intended contract. State what the API promises and distinguish those promises from behavior that is merely visible in practice.
- Test important compatibility expectations. Add compatibility or consumer-driven tests for high-value behaviors, including relevant edge cases that telemetry or client knowledge has surfaced.
- Choose the least disruptive change that meets the need. Prefer additive, tolerant changes where feasible. If clients need different behavior or cannot upgrade together, consider capability negotiation or parallel versions.
- Communicate the migration. Announce deprecations, explain what will change, provide migration examples, and make it possible to track adoption.
- Roll out in stages. Monitor behavior as exposure increases, and keep a rollback path available so the team can respond to unexpected client failures.
The appropriate strategy depends on the number and diversity of consumers, how independently they upgrade, which behavior is observable, the quality of telemetry and tests, and the team’s ability to warn, stage, and reverse a change. No single migration pattern removes compatibility risk.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Scan for outdated or missing drivers - takes under a minute3Clear out junk files and repair common Windows errorsBest Value
What should teams monitor before deprecating a behavior?
Monitor signals that help answer whether the affected behavior is in use, whether clients are moving away from it, and whether the change is causing trouble. A practical review should include:
- Requests and versions associated with the behavior being deprecated.
- Response, error, and latency patterns that could reveal reliance on its current behavior.
- Adoption of the replacement or migration path after warnings and guidance are available.
- Compatibility-test results and client failures during staged rollout.
- Whether rollback or another mitigation is ready if the rollout exposes an unexpected dependency.
Usage data is evidence for a risk decision, not proof that no dependency exists. The team should weigh it alongside consumer coverage, test quality, migration cost, and the consequences of an interrupted client.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
