The most important aspect of any module is not how it implements the facilities it provides, but the way in which it provides those facilities in the first place. -- Damian Conway in Ten Essential Development Practices Public APIs are forever -- (you have) one chance to get it right. -- Joshua Bloch in How to Design a Good API and Why it Matters

Interfaces matter. The more public they are, the more they matter. Indeed, once a public API -- such as Conway's CPAN modules or Bloch's Java SPIs -- attracts widespread usage, changing it becomes practically impossible. By contrast, just about anything else can be easily fixed in a later release.

And yet -- as indicated by Brooks' famous aphorism, plan to throw one away; you will, anyhow -- you're most unlikely to concoct the perfect API at your first attempt.

Making the task more daunting still, the dark art of interface and API design is certainly not an easy one to master, there being many disciplines in play: computer science, human factors (ergonomics), cognitive science, psychology, sociology, linguistics, usability, and so on.

I've spent the past few weeks researching this difficult topic and found very few references dedicated to this subject. Instead, many books devote a section or two to the art of interface design, or perhaps mention it in passing while analyzing a knotty design or coding matter.

This meditation reports the interface and API design references I've found useful and further presents some general interface design ideas and checklists in the hope that they may prove useful -- and that they might be improved upon by your insightful feedback.