Simple APIs

I like simple APIs.

Simple in the sense of small, with few options and few available calls, as opposed to monstrous can-do-everything-APIs. Alright, so maybe I should say small from now on.

Before I tell you why I like small APIs more than bigger ones, let me first tell you why I don't like large ones. There are actually severe drawbacks associated with larger APIs and a bigger selection of available methods and options, but not many people seem to notice, or care.

The first thing that large APIs do with me is make me feel lost. That is obviously true for really large APIs (like the MFC, with which I had first contact when I was fifteen and which probably delayed my programming career by a few years), because there's just so much to see and so much to do that you suffer from the well-known choice paradox as well as sensory overload -- you simply don't know where to look at first, so instead of finding an entry point, I just gave up. But this also applies to smaller libraries where many options are exposed that look like very similar at first glance. Case in point here is the wonderful ELCImagePicker, that I'm using on Imprys. I don't want to bash on this library, it's quite excellent indeed, and I would have had a hard time implementing it myself.

However, and this is the second things that bugs me about large APIs, every time I use the ELCImagePicker, I am left unsure whether I did everything right. Instead of providing a single entry point with a single method and a single callback protocol, I have to compose two classes myself. Two classes. This is about as simple as it gets, but still, it's more complicated than I would like.

Call me lazy (and laziness is probably one part of it), but the more important part is decisions. Programs and program libraries are collections of decisions. The more decisions are encapsulated in a library, the more I can feel safe that these decisions are right in that context, because someone (and probably someone smarter than me) thought about that decision, weighed the pro's and con's of each possible option and then just made the decision. So I don't have to.

This is why I like small APIs: They make me feel safe in my choices.

So what can you do about large APIs? That question is actually quite a philosophical topic, because in a way, each component in a computer program, down to the language you are using, is an API. I think that the only way to handle each and every of these APIs is to make your own, for the situation that you're in. Wrapping lower-level APIs, more or less, because that's what writing programs is, anyway.

So, create a DSL, even if that DSL is "just" a class with two methods. In fact, I think that a class with two methods is probably a really, really good API, and if it fits your program, you should use that. Your program should look like this:

#import "mylib.h"
int main()
{
  mylib.choice choice = mylib.mainmenu();
  mylib.mainprogram(choice);
}

That, right there, is an awesome program. It's powerful, it does what it's supposed to, I can understand it. And it uses all of its underlying APIs.

And that's why I like simple APIs.