Hyrum’s Law: What it means for API Design and Management

The promise and challenges of loose coupling

One of the main aspects of APIs is that they should provide loose coupling, meaning that providers and consumers of services have more independence and autonomy to evolve than in more tightly coupled approaches. The obvious advantage of this is that it requires less time-consuming coordination, and thus providers and consumers can evolve independently.

However, when providers and consumers can evolve independently, there always is the risk of breaking changes. If an API changes, do existing API consumers have to adapt and change? Or can they keep using the API without having to do anything?

Designing APIs for Extensibility is one approach to manage this problem: If the API is designed to evolve and consumers are implemented accordingly, then independent evolution can happen without consumers having to adjust.

Hyrum’s Law: It’s Murphy’s Law for APIs

Hyrum’s Law is named after Google software engineer Hyrum Wright and states that even though you may design your API for extensibility and count on being able to evolve it, things can become more complicated. In particular, when you have many consumers, they may depend on things they shouldn’t depend on. Here is what 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 creates an interesting conflict of interest: On the one hand, the goal for an API is to be consumed, because that is when it creates value. This means that having more consumers is a good strategy to increase the value that an API generates.

On the other hand, the more consumers there are, the more likely it is that (because of Hyrum’s law) some of them are negatively affected by changes in the API that in theory shouldn’t have affected anybody.

Now what?

Where does this leave us? We still want to change things but we also still want loose coupling so that we can change things independently. In Google’s case, it means a lot of sophistication in terms of using the entire codebase (which is available in a mono-repository) and having tooling that looks at both providers and consumers of APIs.

While Google’s scale and sophistication are probably a bit more than what most other developers and architects have to deal with, it still is interesting to look at their strategies and methods and how they may inspire similar strategies at a smaller scale.

If you’re interested in more background and a closer look at what Google does, the following conversation with Hyrum Wrights discusses Hyrum’s Law, what Google does to address the challenges that 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).