Some thoughts on API use and design


All software is building blocks. Exceptionally good software is constructed from orthogonal pieces that fit together like they belong nowhere else, are interchangeable and make the overall structure only marginally more complicated than the components from which it is built. The “seams” or the interfaces between the blocks are the APIs, and it is here, I claim, that most engineering magic happens.

In my experience API design is extremely labor intensive, generally under-appreciated, hard to learn and harder still to teach. The design is almost never right the first time around (or the second time around, for that matter), yet the difference between good APIs and bad ones can be appreciated by looking at software structures that given API makes possible. To give you another analogy from architecture, bad APIs give us shacks cobbled together and teetering on the verge of collapse and good APIs give us Notre Dame cathedrals.

Increasingly software design is all about combining of-the-shelf components into a coherent whole. I’ve noticed it in my day job and while working on JustLiked. The amount of software packages freely available on the internet is staggering and each comes with its own API. In the end we do less in-house API design and more gluing. And every time we need to glue something together, we are faced with the question of what and how to glue.

I think the temptation to reinvent the wheel is huge, so the answer to the question of what and how to glue is often “let’s roll our own”. I don’t mean we are just tempted to write more software–we are tempted to write software which is designed for more reuse than it will ever see. The latter tendency preempts the process of selecting from available ¬†components with designing our own with its own API. I’ve fallen into this trap myself recently, and all I have to say is:

Don’t reinvent the wheel, instead trust the API you are given.

In my view it’s much better to err on the side of more glue than designing a new self-contained, interchangeable building block to fill the void. The more “exposed” and “universal” you want to make these new building blocks and their APIs the less likely you are to succeed on time and on budget. It’s my subjective opinion, but it’s served me well over the years.

Once you find the component you need, use it in the way that it was intended to be used. Every technology has its sweet spot where it shines, so let it shine. Even if you can’t find something that fits perfectly, don’t kludge together a brand new component with its marginally better API because there are hidden dimensions, the secret sauce of API design that you haven’t mastered yet and it will come back and mercilessly haunt you way past your project deadline.

And even when you know what you are doing, make sure that what you are about to do actually gets you any closer to a business objective. Chances are it doesn’t, unless of course you are building an SDK.


Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s