Hyrum’s Law (The Law of Implicit Interfaces)

Image created with Midjourney. Image prompt:
Image created with Midjourney. Image prompt: 2d minimal style illustration Depict a myriad of cables, each representing different behaviors of an API. Some cables are thick and clearly labeled, representing documented behaviors. Others are thinner, less defined, illustrating undocumented but relied-upon features. Users are connected to both types of cables, showing their reliance on both explicit and implicit interfaces

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.

Hyrum Wright

In the realm of software engineering, there's a particular law that highlights an interesting aspect of human behavior: Hyrum’s Law, also known as the Law of Implicit Interfaces. This 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"1.

In essence, Hyrum's Law reveals that no matter how well you define the behaviors of an API, users will inevitably come to rely on even those aspects not officially documented or included in the contract. This can include anything from response times to the specific wording of error messages. To understand the profound implications of Hyrum's Law, let's consider three examples and how it connects to the creation of digital software products.


The Unintentional Error Message Parser

Imagine a software product that interacts with a third-party API. This API returns an error code and an error message when something goes wrong. The official API documentation states that the error code should be used to handle errors programmatically. However, the software product's developers find the error messages more descriptive and start using regular expressions to parse these messages and handle errors. Over time, their code becomes reliant on specific wording in the error messages.

Now, suppose the API developers decide to make the error messages more user-friendly, changing the wording but not the error codes. Despite being an improvement from a user experience perspective, this change breaks the error handling in the software product, illustrating Hyrum's Law. Even though the error messages were not part of the API's formal contract, the software product had come to depend on them.

The Depended-Upon Bug

Consider a digital product that leverages a library's API. This library has a known bug, but instead of causing problems, the product's developers have found a way to exploit this bug to their advantage. When the library's developers finally fix the bug in a later version, the product's behavior unexpectedly changes. Again, this demonstrates Hyrum's Law: the product was relying on a behavior (in this case, a bug) that wasn't part of the API's official contract.

The Timing-Dependent Integration

Lastly, imagine a real-time application that uses a cloud API for data processing. The developers of this application have noticed that the API typically responds within a certain time frame, and they've implicitly built this timing into their system. When network conditions or server loads fluctuate and the API's response time changes, the real-time application suffers performance issues or even fails entirely. The response time was not guaranteed by the API, but the application had come to rely on it regardless, exemplifying Hyrum's Law.

Connecting Hyrum’s Law to Digital Software Products

In software product development, understanding and acknowledging Hyrum's Law can help teams make more informed decisions about their use of APIs and their approach to versioning and backwards compatibility. It's a reminder to document and communicate not just the explicit contract of an API, but also any significant observable behaviors. It also highlights the importance of considering how changes – even seemingly benign ones – may impact users.

Furthermore, Hyrum's Law underlines the value of thorough testing, which should cover not only the formally defined behaviors of an API but also edge cases and undocumented behaviors that users might have come to rely on.

Finally, Hyrum's Law serves as a reminder of the responsibility that comes with creating APIs. As developers, it's easy to think that we have control over how our APIs are used. However, once an API is released into the wild, it will be used (and depended upon).

See also