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:

 

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.