On API Design Guidelines

Update: Good news! Jaroslav Toulash emailed me that he published a book on Practical API Design !!!

Looks like Brian McAllister may be preparing a talk on Designing Elegant APIs.

I've been very interested in good API design for a long time. But I could never find a single book on the subject. Many design and programming books provide good advice and guidelines that are essential for designing good APIs, but none of them tackles the matter directly.

I reviewed "Interface Oriented Programming" a few months back with disappointment. It may not be a bad book, but I felt it was quite basic and superficial. May be my expectations were too high, and too focused on API design.

Over time, I collected some links on the subject and shared some with Brian:

• Best Practices in Javascript Library Design (via John Resig on JavaScript API Design) - A good presentation given by the author of JQuery.

• API: Design Matters - Article by Michi Henning, ZeroC, for ACM Queue magazine.

• How to Design a Good API and Why it Matters - Excellent deck from Joshua Bloch. There's also a video of his presentation at JavaPolis 2005.

• Interface Design, Best Practices in Object-Oriented API Design in Java, by Bill Venners - This one is a Book in progress!. Unfortunately, the last updates seem to be from 2002 or so. I'm not sure if the project is still alive. Anyway, it contains many good articles.

• How To Design a (module) API - A great page on good design practices for writing APIs. It's tailored for NetBeans module writers, but is still pretty general and gives very valuable guidelines.

• How to Write APIs That Will Stand the Test of Time - A session I attended at JavaOne 2006. Presented by Tim Boudreau and Jaroslav Tulach, members of the NetBeans team. It focuses on API evolution and compatibility, but also covers usability and other guidelines. I guess they are the main guys behind NetBeans' How To Design a (module) API page linked above.

  I had the chance to speak with Jaroslav after his session and suggested he should write a book on this topic. I emailed him the references I had, and he said he would try to draft something by the end of year.

• API Usability - Focused on making APIs easy to use. The article applies general usability principles (commonly used in GUI design) to the design of APIs.

• Measuring API Usability - An interesting article by a usability engineer at Microsoft, published on Dr. Dobb's. It favors the use of scenario-based design to achieve usable APIs, and explains the use of their "cognitive dimensions" framework for measuring API usability. He also blogs about API usability.

• Krzysztof's Laws of API Design - From another Microsoft blogger on API design.

• Java API Design Guidelines - A good article from a developer who was also surprised by the lack of a book about API design. He collected some advice and additional links.

• XOM Design Principles - Some design "principles" followed by XOM (an XML parsing library).

• The Most Important Design Guideline? - A short article by C++ guru Scott Meyers.

• Humane Interface, Minimal Interface, Designed Inheritance, DSL Boundary, Duck Interface, Fluent Interface, Public vs. Published Interfaces - Some of the many great writings from Martin Fowler. These selection is on specific topics that are relevant to API design. Most of them are quite recent.

• Programmers are People, Too - An article by Ken Arnold for ACM Queue magazine: "Programming language and API designers can learn a lot from the field of human-factors design."

So, let's hope Brian gives his talk at a big conference, signs a contract with a big publisher and fills the void.