esc
Anthology / Yagnipedia / Hyrum's Law

Hyrum's Law

The Contract Was Never the Contract
Principle · First observed 2012 (Hyrum Wright, Google — who merely named the thing that had been breaking APIs since the first API existed) · Severity: Thermodynamic (increases with user count; irreversible past a threshold nobody can identify until after it has been crossed)

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.” It was articulated by Hyrum Wright at Google, who did not so much discover a new principle as give a name to the oldest betrayal in software — the moment when what your system does becomes more binding than what your system promises.

The law is sometimes called the Implicit Interface Law, which is accurate but lacks the poetry of a proper noun. Laws named after people carry more weight. Newton did not call it “the implicit gravitational acceleration observation.”

“You documented three fields. You returned five. Someone is parsing the fourth one in production right now, and they will file a bug when you remove it.”
— The Lizard, reviewing a ’non-breaking’ API change

The Mechanism

Every API has two interfaces: the one you wrote down, and the one your users reverse-engineered from observation.

The documented interface says: this endpoint returns a JSON object with fields name, status, and timestamp. The observed interface says: this endpoint returns a JSON object with fields name, status, timestamp, the fields are always in that order, the timestamp is always UTC, the status is always lowercase, the response arrives in under 47 milliseconds, and there is a trailing newline.

You documented three promises. You made six. You know about three of them. Your users know about all six, because your users do not read documentation — they read responses. They copy a response into a test fixture, assert on every byte, and ship to production. The test passes. The fixture becomes the contract. The documentation becomes a historical curiosity, like a medieval map that says “here be dragons” over a region that now has a Starbucks.

“I once watched a team break fourteen downstream services by fixing a spelling mistake in an error message. The error message was not part of the API. The error message was not documented. The error message was parsed by regex in fourteen production systems. The spelling mistake was the API.”
— The Caffeinated Squirrel, vibrating at a frequency that suggested personal experience

The webMethods Pipeline: A Field Study

The most architecturally complete demonstration of Hyrum’s Law in the wild may be the webMethods Integration Server pipeline.

webMethods services communicated through a pipeline — a shared, mutable data structure passed between service invocations in a FLOW chain. A service received the pipeline, performed its work, placed its documented outputs into the pipeline, and passed it to the next service. This was the contract.

The pipeline, however, was not a sealed envelope. It was a shared workspace. Services left artifacts in it beyond their documented outputs — intermediate variables, debug flags, temporary calculations, vestiges of internal logic that happened to remain in the shared data structure because nobody explicitly removed them. The pipeline was a river, and every service upstream left sediment.

Downstream services noticed the sediment.

At first, one or two integrations quietly relied on an undocumented field — a convenient shortcut, a value that was always there even though no specification promised it would be. Then more. Then dozens. Then the sediment became load-bearing. The undocumented artifacts in the pipeline were not side effects anymore. They were the interface.

When webMethods needed to modify service behavior — to clean the pipeline, to change internal implementations, to remove the sediment — they discovered that the sediment was structural. Removing an undocumented variable from the pipeline broke production integrations that had been running for years. The documented contract was irrelevant. The observed pipeline contents were the real API, and the real API included everything every service had ever accidentally left behind.

The solution was not to fix the old calling convention. The solution was to build a new one.

webMethods introduced an alternative invocation mechanism that used explicit maps — a way to call services where the inputs and outputs were explicitly declared and isolated, specifically to prevent the pipeline contamination that had turned undocumented side effects into contractual obligations. The old convention was preserved. It could not be removed. It was a monument to every integration that had ever parsed the sediment and called it stable ground.

“They didn’t deprecate the old way. They couldn’t. Deprecation implies that someone will eventually stop using it. Nobody stops using undocumented behavior. Undocumented behavior is forever.”
— The Lizard, on the half-life of observable side effects

The Universality

Hyrum’s Law is not specific to APIs, pipelines, or webMethods. It applies to every system with users.

The number of users required to trigger Hyrum’s Law is not large. It is not “Google scale.” It is any number greater than one, given sufficient time. One user with sufficient desperation will depend on any observable behavior within a single afternoon.

Postel’s Law says: be conservative in what you send, liberal in what you accept. Hyrum’s Law is the consequence: whatever you send, conservative or not, someone will depend on every byte of it. Postel’s Law is the advice. Hyrum’s Law is the punishment for following it.

The Relationship to Conway’s Law

Conway’s Law says your system’s architecture mirrors your organisation’s communication structure. Hyrum’s Law says your system’s actual interface mirrors your users’ observation structure. Conway determines the shape. Hyrum determines the surface area. Together they guarantee that every system is both larger and more tightly coupled than anyone intended.

Measured Characteristics

See Also

See Also