How to Write A Good API
A lot has been written about how to design a good user interface, but very little about how to design a good programming interface (API: Application Program Interface, or a library). This is somewhat surprising, since an API is nothing more than an UI for programmers, and programmers are normally good at writing tools for each other.
The single biggest mistake API designers make, I think, is that of designing the interface in terms of what’s easy to implement, rather than what’s useful to the end-user.
An everyday example of this is the common bathroom faucet1: there are two pipes coming to the sink, one with hot water and another with cold. An ordinary faucet deals with this the easy way: put a tap on each pipe that regulates how much water from each pipe flows to the sink.
This is obviously trivial to implement, but also misses the point: what the user really wants is to set the amount and temperature of the water. With a two-tap faucet, there’s no way to set either one directly: if you want more water and open the hot tap more, you get more water, but change the temperature; so you need to open the cold tap some to compensate.
A better design is the type of faucet with a lever that goes up and down to regulate the flow, and left to right to set the temperature. This is more work on the faucet designer’s part, but has the advantage of giving the user a simpler interface, one where there’s a direct way of doing the things the user wants to do. This may not seem worth it for a simple faucet, but I hope you’ll see that this approach can pay big dividends with more complicated systems.
When you’re designing an API or writing a library, don’t go the quick route of writing what’s easiest to implement.
Think about what kind of code you, as a user of your library, would like to be able to write. Write some “dream code” to see how it looks, and where it can be improved.
Given a spec, any fool can write a library that interfaces with a given hardware device, network service, file format, or whatever. What’s harder but much more useful, is writing a good library.
By “good” here I mean useful, elegant, and fast. One that your users will enjoy using. And your users aren’t drooling mouth-breathers who can’t remember whether to double-click on the Internet, but hackers and coders like yourself; people who, if they don’t like your library will switch to another one without a second thought, or even take much pleasure in writing their own.
[1]Example taken from Donald Norman’s The Design of Everyday Things.
Pick two.
(Sorry, had to be said!)
Pick at most two.
Of course, a geek would have talked about maximizing the weighted sum of all relevant criteria, possibly in a bumpy fitness landscape.