Hyrum's Law

Hyrum's Law states:

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.

Named after Google software engineer Hyrum Wright, this observation highlights a fundamental challenge in software engineering: as a system scales and its client base grows, the "real" interface of the system expands beyond its documented specification to include every single one of its observable characteristics.

Core Concepts

1. The Explicit vs. Implicit Contract

An API has two definitions:

• The Explicit Contract: The official, documented specification (e.g., OpenAPI schemas, gRPC proto files, or API reference guides) detailing the guaranteed inputs, outputs, and behaviors.
• The Implicit Contract (All Observable Behaviors): Any side-effect, performance characteristic, error message, order of returned results, response latency, or bug that a client can measure, observe, or exploit.

As usage increases, client developers will inevitably optimize or write code that relies on the implicit contract, converting implementation details into hard dependencies.

2. Common Observable Behaviors

Clients often build dependencies on undocumented behaviors such as:

• Sorting Stability: A database return order that happens to be alphabetical or ordered by insertion sequence but is not officially guaranteed in the API spec.
• Error Formats & Wording: Hardcoded regex checks on human-readable error strings rather than error codes.
• Performance & Latency: Expecting synchronous speeds or specific response latencies for particular requests.
• HTTP Header Casing: Relying on standard casing (e.g., Content-Type) when HTTP specs declare headers are case-insensitive.
• Undocumented Side Effects: Assuming a write operation in one service instantly propagates to a read database, bypassing eventual consistency bounds.

3. The Scalability Friction Paradox

The more successful an API or system becomes, the harder it is to evolve. Every change to the underlying code—even optimizations that strictly preserve the documented contract—carries a non-zero probability of breaking a client.

Visualizing Hyrum's Law in Action

Below is a sequence diagram showcasing how an internal performance optimization breaks a consumer because of their reliance on an undocumented implementation detail (sorting order):

Strategic Utility: Why CTOs Should Care

For technology leaders, Hyrum's Law is not just a theoretical software pattern; it represents a major source of technical debt and delivery friction.

1. Impact on Delivery Velocity

Hyrum's Law acts as a brake on architectural evolution. When engineers are afraid to refactor, upgrade databases, or migrate internal systems because "something might break," delivery slows down. The cost of changes climbs exponentially relative to the scale of the user base.

2. Risk Mitigation & Governance

Understanding Hyrum's Law allows CTOs to move from reactive crisis management (fixing broken integrations after a release) to proactive architectural design. It forces engineering teams to design interfaces that are resilient to scale.

Actionable Leadership Strategies

To mitigate the friction caused by Hyrum's Law, engineering organizations should adopt the following tactical practices:

1. Design for Chaos (Intentional Variation)

Prevent clients from relying on undocumented behaviors by introducing controlled instability into non-contract responses:

• Order Shuffling: Explicitly randomize JSON keys or unsorted array elements before returning them.
• Header Shuffling: Randomize header casing in staging or production.
• Latency Injection: Introduce subtle micro-latencies to prevent clients from relying on fast internal network times.

2. Consumer-Driven Contract (CDC) Testing

Transition from monolithic integration tests to CDC testing using tools like Pact. Consumers publish their expectations of the API contract, and providers run these contract tests in their CI/CD pipelines to detect breaking changes before deployment.

3. Progressive Delivery

When deploying changes to high-traffic APIs, utilize:

• Canary Deployments: Route a fraction of traffic to the new version to detect client regressions.
• Shadow Traffic (Teeing): Mirror live production requests to the new service in parallel, comparing the results and latencies to ensure observable behaviors remain identical for critical integrations.

4. Explicit Deprecation & Versioning Policies

Define strict deprecation policies backed by automation:

• Add Deprecation and Sunset HTTP headers to response streams.
• Use telemetry to track which clients are still invoking legacy behaviors before turning them off.

See Also

• Gall's Law – How complex systems successfully emerge from simple, working ones.
• Boy Scout Rule – Keeping codebase quality high during constant modification.
• Architectural Decision Records (ADRs) – Documenting explicit architectural choices and constraints.
• REST APIs – Standard practices in API structure.
• Iceberg Model – Looking below surface-level events to understand systemic structures.

References

• External Links:
  • Hyrum Wright's Official Site – The primary documentation of the law.
  • Software Engineering at Google Book - Chapter 1 – The open-access online version of the book introducing Hyrum's Law to the industry.
  • Wikipedia: Hyrum's Law – General reference and context.