I just ran across a pretty good CACM article on API design. This is a topic I feel very strongly about. In numerous interviews, as I was touting my user-interface design skills, my interviewer has said something along the lines of, "But ours is a batch-mode product; it doesn't have a user interface." My usual response to this is that all programming, especially API design, is user-interface design. The exact same principles that make a good user interface apply to a programming API, and indeed to programming in general. A program is (among other things, obviously) a user interface between programmers, including between you and your future self. A poorly-designed API (or more generally, poorly designed code) is a long-term source of friction, and as with most design work, extra time spent at the beginning to create a usable interface can have a tremendous return on investment.
As that article mentions, a really good API almost disappears. Methods exist to do what you want, they are named what you expect them to be, and they do what you need them to without requiring any gymnastics of the sort described in the article. The only two APIs I've ever seen that come close to what I would consider the gold standard are Qt and OpenAccess (disclaimer: I worked on the latter, so I may be biased there).
A search for API usability guidelines turns up a number of good resources on the topic, such as this one and this one.
Labels: api, design, programming, usability
One big difference between a "real" user interface (i.e., a human interface) and an API is that in an API you not only can but must demand a degree of precision and rigor in the inputs that would be unthinkable for a human interface.
Having also worked on OpenAccess, I'm not sure I'd hold it up as such a great example. For one thing, it forces C++ programmers to interact with a complex database in a totally non-OO manner.
My citation of OA doesn't mean that it's perfect, so much as it illustrates just how bad most APIs are that this one is among the best I've encountered. Also, as I said, I'm surely biased, not only by hubris but also because I'm intimately familiar with it, so of course it feels natural to me.