Hyrum's law for API behavior

API change and its impact

One of the challenges with large projects is that of maintainability. When you are building complex systems that are going to be in use for many years, it is important to take into consideration the challenge of long term maintainability.

In that context it is important to know about “Hyrum’s law”.

“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.”
– Hyrumslaw.com

This is very important consideration when you make changes to the system. Even with the careful considerations and good practices of rigorous code review, we cannot assume perfect adherence to the published contracts in the API. It might be possible that sticking to the interface is alone sufficient, but it also depends on what kind of dependency that a user of the API has taken. Given enough time and users even the smallest change would break something.

An example is that as part of our REST API contract we returned the pagination links. The pagination links were supposed to used as it is and should be used to get the next page of data. As part of a fix we change the pagination link from upper case to lower case. But for some reason certain apps using the API has taken dependency on the casing of the pagination links which broke their application. Since this was not part of the actual contract we never expected that the end users would be impacted.

As you see any change that you make you need to find a way to investigate, identify and fix those breaking changes.

So the lesson learnt is be careful with your change and do not change for the sake of change, but must capable of evolving your software with time.

In summary the changes to the implementation must now conform to both the explicitly documented interface, as well as the implicit interface captured by usage. Sometimes referred as "bug-for-bug compatibility." :)