Write APIs You Want to Use

First post on Medium, insert “hello world” here, etc etc. Nothing too deep the first time around.

Every programmer who’s developed more than a day in his or her life has used an ugly API or library that is awkward and difficult to use. An API for which you had to develop another API to use in a sane way. These APIs waste time and money. Undoubtedly most of us are guilty of writing one or two of these. Or more.

One solution to keep from writing bad APIs is to write the API first. That is, write the documentation for whatever you’re creating before starting. It’ll change as the API is implemented, of course, but it gives you an end result to build towards.

For web design, I liken the process to creating a design in Photoshop (or a similar tool) rather than designing in-browser; you create a resemblance of the end product first without being tied down with implementation details. It also saves resources: it’s significantly easier to drag a layer over than it is to punch your stylesheets until the desired result is obtained.

Developing the API first a practice somewhat more common in the world of statically typed languages such Java, where one can explicitly write the interface itself without worrying about business logic. But I’ve seen it happen few times when developing in languages such as JavaScript or Python (or even PHP, which does provide interfaces).

Why ‘API First’?

API First will save you from writing bad APIs. Bad APIs cost undue time and money; it takes precious development time to understand them, and there’s more cognitive load when using them. In the worst cases, one might even end up writing wrapper APIs: yet more code to maintain, test, and debug.

Other essays that touch on this same vein point out that, since you often know where your module is going inside some larger application, you can tailor the API to be easy to use in that situation. I disagree. I think that writing a good, general purpose API for a given module saves you from some of the pain of the Rule of Threes. Atwood quotes that:

It is three times as difficult to build reusable components as single use components, and

I will not reject this rule outright. However, I do think that it is much closer to three times more difficult — and often less if the module’s scope is narrow — if the module is built with a good API first. It is also more pleasant to expand on its functionality when you don’t feel the urge to fix bad parts, which would in turn be breaking changes and have to be propagated upstream.

I would hesitate to give it such a grandiose term as “API Driven Development” — although some have given it to similar ideas, a quick Google shows — in part because it’s not a replacement for processes like TDD or BDD. But it does help you write better, more beautiful code. And that’s what we’re here for.