Every API has a contract that describes how it behaves. However, this contract is often not explicitly documented, but is instead defined by the implementation itself. Hyrum’s Law states that with enough users, every observable behavior of a system becomes a dependency that a third party relies on being present. This includes even those parts that were never explicitly documented.
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.
Why Hyrum’s Law Occurs
The reasons why Hyrum’s Law occurs are manifold. One main reason is the diversity of users and their different use cases. While the developers of an API implement certain functions and behaviors, users may apply them in unexpected ways. This means that even small changes in the implementation can have unintended effects on users.
The following factors can, for instance, contribute to Hyrum’s Law occurring:
- Different usage patterns: Users may use the API in ways that the developers did not anticipate. This can lead to certain behaviors being regarded as “binding,” even though they are not part of the “official” contract.
- Missing documentation: When certain behaviors are not documented, users may nevertheless rely on them, especially when these behaviors are observable and occur consistently.
- Third-party dependencies: When other systems or libraries rely on certain behaviors of the API, this can lead to changes in the implementation causing problems.
A Practical Example
For a catalog item in ServiceNow, the requirement was, greatly simplified, that a certain number of file attachments had to be present when submitting the form. Otherwise, the form submission should be aborted with an error message.
The problem: At that time, ServiceNow did not provide an officially supported OOTB function for checking the number of file attachments. The only practical solution was to traverse the Document Object Model (DOM). This approach, however, has the disadvantage that the implementation may no longer work with future updates.
The decision: After a thorough risk analysis and pointing out the limitations, the customer deliberately opted for the DOM traversal, since this functionality was a fundamental prerequisite for an efficient business process and no reasonable alternative existed at that time.
The implementation: To maximize the stability of the implementation, several measures were taken:
- Selecting a stable query selector that will most likely remain unchanged even with future ServiceNow updates.
- Using the undocumented
getCurrentAttachmentNumber()function, which is used internally by ServiceNow via AngularJS, instead of thelengthproperty of aNodeList. This reduces the dependency on volatile DOM structures. - Incorporating targeted error handling: If the implementation breaks due to an unexpected update,
then a meaningful error message containing the
sys_idof the configuration record is thrown. This message contains all the information a future developer needs to quickly identify and resolve the issue.
The insight: In this case, Hyrum’s Law still applies, because an undocumented behavior is being exploited: the counting of file attachments via the DOM. However, careful implementation and the selection of the most stable query selectors possible significantly reduced the probability that a future update would break the functionality.
This practical example clearly shows the developers of an API how Hyrum’s Law can occur in the real world. For users of an API, however, it also demonstrates how deliberate error management and conscious design decisions can reduce the impact of unforeseen changes to undocumented behavior.
Dealing with Hyrum’s Law
Hyrum’s Law cannot be completely avoided, but there are strategies to minimize its effects:
- As a user of an API, it is important to be aware of the effects of Hyrum’s Law. Relying on undocumented behaviors should be avoided if possible. Instead, users should consult the official documentation and rely on the guaranteed functions and behaviors.
- As a developer of an API, it is likewise important to be aware of the effects of Hyrum’s Law. Developers should strive for stability and consistency, since frequent changes to observable behavior can introduce unintended breaking changes for downstream users and dependents.
Conclusion
Hyrum’s Law does not have to be followed as a rule. It has to be understood as a reality and taken into account by developers as well as users of APIs. Because with a sufficiently large user base, every observable behavior can become a dependency, even if it is not part of the explicitly agreed contract. The signals a system exposes should be deliberately designed by its developers. Users of an API should only rely on those signals that have actually been guaranteed and documented by a system. When undocumented behaviors have to be relied upon, this should be done with care and in consideration of the risks.