Recently I’ve been thinking about APIs. Pause for a moment to consider the best API family you’ve ever used. Dreamy, wasn’t it? Everything worked the way you expected, you barely needed to look at the API reference, and the resulting code virtually documented itself.
Now think about the worst. I recall when I first started doing Windows programming and came across LPARAMs and WPARAMs in Windows messages. The whole concept of passing nebulous parameters that might be pointers or might be values was quite disconcerting. Or how about this fun little tidbit in the documentation for RegQueryValueEx: "If the data has the REG_SZ type, the string may not have been stored with the proper terminating null characters. Therefore, even if the function returns ERROR_SUCCESS, the application should ensure that the string is properly terminated before using it." I wonder how many applications have been bitten by this API issue?
Creating great APIs is hard. But wow, is it important for those of us who ship code libraries to developers. When we don’t get APIs right, there’s nothing that can truly compensate for the failure — not great documentation, not great sample code, not great user education.
Here are some principles my teams have been using as we think about APIs:
- APIs must be intuitive and discoverable. AddToolbarButton is more intuitive than ExecCommand. A developer reading the function prototype should have a great understanding of the function without reading docs.
- APIs must be simple. They should do one thing perfectly and do no more. APIs that take the swiss army knife approach are not simple. APIs with a long list of parameters are not simple.
- APIs must be difficult to misuse. They should use strong typing that help developers find errors at compile time rather than runtime.
- APIs must not have unexpected side effects. Functions that set globals are evil.
- APIs must be consistent. Developers come to rely on certain idioms and conventions, including naming, parameter usage, parameter order and so forth. It’s better to match well-known idioms than invent new ones.
- APIs must be reviewed before coding. Refactoring APIs is costly. Getting them right at the very beginning is worth the upfront cost.
- APIs must be reviewed by the right people. The right people typically include subject matter experts, people in different disciplines, and potential customers. For instance, an audio API should be reviewed by audio experts. Disciplines might include developers, testers and documentation writers.
If you’re developing your own API set, these guidelines can help ensure that your customers have that dreamy experience developers get when using a great API. You’ll also spend less time having to update documentation, write complex sample code, or staffing a large support team.