Designed for Adaptability - Future Proofing APIs

Today, I want to discuss what truly makes an API great. Sure, we all know the basics of good API design - it should be memorable, unambiguous, and promote readable, correct, and performant code. These are the “first order” aspects that library developers typically focus on initially. They’re important, but you might have to make some trade-offs along the way.

However, there’s more to it than just nailing these fundamental principles. Unless you’re building something for a Mars rover that will never change, your code and the code of those using your API will likely evolve over time. That’s where the true masters of API design shine.

The best API designers I’ve worked with don’t stop at the “first order” aspects like readability. They put just as much effort, if not more, into what I call the “second order” of API design: how code using this API would evolve over time.

You see, even the most elegantly crafted code can crumble under the slightest change in requirements. Great APIs anticipate this inevitability. They foresee that you’ll want to move code around, copy and paste portions, rename elements, unify special cases into reusable helpers, unwind abstractions back into specific cases, add a quick hack, optimize bottlenecks, throw away and rewrite parts, make mistakes, navigate between cause and effect, fix bugs, and review those fixes.

These exceptional APIs don’t just help you fall into the pit of success but ensure you can stay there, even as your codebase morphs and adapts. They’re optimized for change, designed to be future-proof and adaptable.

So, while those “first order” aspects are crucial, the true hallmark of a great API is its ability to gracefully accommodate the inevitable evolution of your codebase. It’s an API that empowers you to refactor, optimize, and iterate without becoming a hindrance itself.