Embrace Hyrum’s Law

May 26, 2023

If you’re a library or service developer, be keenly aware of Hyrum’s Law, which 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.

Your primary job is to deliver a feature, not an API. The API is merely a way to deliver that feature. Breaking your feature breaks your client’s product, even when the change strictly adheres to the API.

Consider every change across the API boundary (except maybe adding new API) a potentially breaking change. Have a communication channel to tell (known) clients about your upcoming change. Invite clients to test your change with you. If deploying to a service, watch your deployment, and revert it at the first sign of trouble.

With a popular enough API, there will be clients you haven’t heard of that depend on your implementation. Give yourself way more time than you think to roll out your changes.