A Good API: g9

Once in a while an API comes around that makes me stop and and look at what I’m doing.

Like many aspects of design, when it comes to APIs, what is not there matters as much as what is. Engineers like to fiddle around with things. So they like to add knobs and dials for fiddling around with things.

People say platitudes like good API design has to do with balancing flexibility and simplicity. People throw around the word “simplicity” as if people just need to be reminded of it and all will be well. “Simplify your API” isn’t the same as “put on sunscreen.” It takes work. Lots of work. Intentional work with the goal of simplifying because there is little chance you are going to arrive at the right solution by accident.

An example of a good API is g9.

Before you look at it, think about how you would construct an API that:

• … allows you to draw a diagram on an HTML canvas – perhaps with a limited set of drawing primitives.
• … once the diagram is rendered, allows users to manipulate the diagram by dragging points around.

There are millions of ways of designing this. But g9’s approach takes the cake. You can take a shortcut and have a look at their API documentation or their examples. But basically it is this:

1. Tell us what your mutable parameters are.
2. Draw your diagram with based on the set of parameters.
3. …

That’s it. That’s all there is.

Now, you can sit there and come up with a million knobs that you claim makes the API more powerful. And you might be right – you’ll be able to do more things with the API with the knobs you add.

But when you start treating simplicity as a feature, you’ll notice that adding knobs isn’t the same as making a more powerful API. All those additional knobs must be essentially invisible for people who don’t need them. Otherwise every addtional knob will waste more of your users’ time and energy for nothing.

The power of an API comes from letting users to express more with less.