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.
-- Hyrum’s Law
Or, what’s old is new again. The earliest reference to Hyrum’s Law I could find was in late 2016, but that’s hardly the first time I ran across the idea. That’s just the name with the weight of Google behind it.
I ran across a variant of it when I was working on Falcon 4.0. Our testers decided some debug code was a great feature, so we ended up shipping it. After that I went to work for this little software company called Microsoft. Microsoft was the dominant force in the industry for many reasons at the time. At the time, and still, to a large degree, Microsoft focused on the enterprise customer. Customers who would have 10s or 100s of thousands of licenses and build lots of internal tools and processes use Microsoft products. And not just Windows/Office. Flight Simulator sold 100s of thousands of copies of each version. From the operating system to the office suite, to games, companies lived on MS software. And when you have a single customer with that many licenses you listen to what matters to them.
And one of the things that was important to customers was that things keep working. We dealt with that a lot on Flight Simulator. We spent a large percentage of our time in each development cycle making sure things were bug-for-bug compatible. In Windows it turned into an entire feature of its own, Compatibility Mode.
But unless you’re building the actual end user experience(and even there, your bug is their feature), you need to have some kind of interface to what you’re building. If there’s no way to provide input/read output it’s not doing anything but turning electricity into heat, so there will be some kind of API. Given that constraint, there are a few things to keep in mind.
- Version your API: Get people into the habit of specifying the version, so when it changes it’s not a mental shift.
- Eliminate, or at least minimize side effects: The fewer side effects, the less likely sers are to start depending on them.
- Keep the API as focused as possible: The bigger the surface area of your API, the more unique combinations of things users will come up with/
- Expect the unexpected: Users will come up with new and interesting ways to use the API that you didn’t intend. Be prepared to support them
- Instrument your API: That way you can understand how it’s being used and be less likely to be surprised when something stops working.
