Hyrum's Law: What It Means for API Design and Management

The Promise and Challenges of Loose Coupling

APIs should be built around the idea of loose coupling – that providers and consumers of services possess more independence and autonomy to evolve. The obvious advantage of this approach is that it requires less time-consuming coordination, and thus allows providers and consumers to evolve independently.

However, independent growth presents an increased risk of breaking changes. Will existing API consumers have to adapt to every development? Or can they continue using the API in an unaltered state? 

Designing your APIs with extensibility will help manage this problem. An extensible API will continue to grow while still remaining accessible to all current and previous users.

Hyrum's Law: Murphy's Law for APIs

Hyrum's Law is named after Google software engineer Hyrum Wright. For the uninitiated, Murphy's Law states that if something can go wrong, it will. Likewise, Hyrum's Law follows that even if you design your API for extensibility, an API with many active users will likely grow to depend on the wrong aspects. Hyrum's Law says:

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.

This presents a conflict of interest. An API creates value through its use, so more users will increase its value. However, Hyrum's Law posits that as more users adopt the API, it will undergo more changes. These will negatively affect the overall userbase who, in theory, shouldn't have been impacted by individual changes. 

Now What?

Where does this leave us? We want a unified and consistent experience for users, but we also still desire loose coupling. Google relied on a highly sophisticated solution that used the entire codebase (available in a mono-repository) and created tools to serve both providers and consumers of APIs.

While Google's scale and polish may present unrealistic goals for most other developers and architects, their strategies and methods still provide an interesting case study that may inspire similar strategies on a smaller scale.

If you're interested in more background and a closer look at what Google does, Check out the below conversation with Hyrum Wright to learn more about Hyrum's Law, how Google addresses the challenges it creates, and the recently published book "Software Engineering at Google: Lessons learned from Programming Over Time" (Titus Winters, Tom Manshreck, and Hyrum Wright, March 2020, O'Reilly). 

If you liked this video, why don't you check out Erik's YouTube channel for more "Getting APIs to Work" content?