Why I Hate APIs

APIs stand for application programmer interface, or something like that.

For the non-programmers out there, imagine you have a programmable robot. It can take a limited number of commands. Move forward X units. Move backward X units. Turn left X degrees. Turn right X degrees. Blink lights. Stop blinking lights. These commands can be thought of as an API. It tells you want you can do with the robot in a nice, succinct way.

Programmers rarely write everything from scratch. The rely on code other people have produced. At a minimum, these other coders provide an API, i.e., a list of things you can do.

The problem is that sometimes all you get is the API, and it may not be obvious what convoluted idea they had in their head when they came up with it. Maybe they're really mathematical, and feel that everything needs to be expressed in terms of some elegant, yet frightfully obscure theory. To explain the theory would take a Ph.D., yet they can't be bothered to explain why.

I'm reading some API for some GUI (graphical user interface, stuff like menus, lists, buttons, etc). About 1/3 of the commands of most GUI widgets (a menu or a button or a list often gets a generic name like "widget") are useless. There aren't pointers to say "most commonly used method", or more importantly, what stuff you can or can't do.

Ideally, what you'd do is give a list of requirements (this is software engineering speak for "what should it do"), and the motivation behind it, plus anti-requirements ("the stuff it isn't supposed to do"), which is tough, because you are guessing at what you think users might want to see, but you don't intend to do.

Although seeing actual code is a little bit of an improvement, it still misses the motivation for what people want to do. This one code had a "mixin". Um, how was I supposed to know that I could use that? It's not in the API!

The lesson is that documentation often sucks, because people hate to write it. Coders believe in code, and not much else. If they believed in documentation more than code, maybe coding would be a little more fun.