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
Before you look at it, think about how you would construct an API
… 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:
Tell us what your mutable parameters are.
Draw your diagram with based on the set of parameters.
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