Ferenc Mihaly maintains a blog call the Amiable API where he posts various articles on API design. As part of this blog, he provides a checklist of dos and don’t in API design. The list is focused on the Java programming language, however, most of what Ferenc presents it applicable to other languages too. I really like the bullet list format and the use of verbs to produce a concise yet extensive set of general rules to consider when developing an interface.

• http://theamiableapi.com/2012/01/16/java-api-design-checklist/

Finish software house Reaktor has published some slides on how to design good APIs. The authors, Jari Mäkelä and Ville Peurala, make the point that bad APIs can infect client code and lead to bad client code too. They state that some elements of good design include being intuitive, easy to learn from simple examples, self explanatory, and effort minimizing. A good API should make correct usage easy and wrong usage difficult or impossible. They provide a number of code examples of bad and good API design decisions – these examples are in Java but are pretty vanilla and easily applicable to other languages. The slides are provided as a PDF download at:

• http://reaktordevday.fi/slides/ApiDesign-ReaktorDevDay.pdf

Dr. Jaime Niño of the University of New Orleans has produced teaching materials to support his class on API development. This 6-page document covers a lot of the important API topics, from specification, documentation, design, implementation, and testing. These principles are illustrated with reference to the task of creating an API for data containers. Some of the words of advice include:

• Make the specification of the data type for the container as generic as possible
• Specify data containers via interfaces
• The data container interface must provide a cohesive abstraction
• Be consistent
• Be minimal
• Methods names matter
• Favor queries
• Minimize the number of commands
• Favor parameters’ type specified via interface types
• Use appropriate parameters and return types
• Avoid long parameter lists

You can view a PDF of the document here: API Design Principles in CS2.

Eamonn McManus wrote this blog article about API design guidelines for Java. This includes some generic words of advice such as designing for change, being minimal, being easy to use and learn, etc. In terms of Java specific guidelines, McManus talks about the problems of using interfaces and packages, and provides specific advice such as using immutable classes, static final fields, and avoiding Cloneable.

• http://www.artima.com/weblogs/viewpost.jsp?thread=142428

Jakob Jenkov has compiled an extensive collection of tutorials on how to design good APIs. Jenkov summarizes the qualities of a sound API with the statement: “Solve my problem, with minimal effort from me, and don’t get in my way.” His tutorial is broken down into several sections, including: Lots of Upfront Design, Keep it Small and Focused, Don’t Expose More than Necessary, Sensible Defaults, Optional Abstractions, Central Point of Access, among others. His tutorial covers a lot of ground and offers a lot of valuable tips, including several code examples in Java to illustrate his points.

• http://tutorials.jenkov.com/api-design/index.html

Kevlin Henney wrote a white paper on patterns in Java called The Temptations of Symmetry. Here he suggests that software designs should be biased toward symmetry because symmetric designs tend to be simpler and hence easier to use. The paper includes sections on Returning What You Borrow, Not Returning What You Didn’t Borrow, Fault Injection, and Encapsulating What You Borrow. You can download a PDF version of the document from the following link:

• http://www.two-sdg.demon.co.uk/curbralan/papers/javaspektrum/TheTemptationsOfSymmetry.pdf

Ricardo Cabral has compiled a set of API design guidelines, including general guidelines and Java/C++ specific ones. This includes best practices such as being minimal, being complete, having clear semantics, being intuitive, and being easy to remember. Many of these come from the Qt API Design notes, but there are some further suggestions in there too, dealing with static and dynamic polymorphism, enums,  and reference/pointer use in C++. See:

• http://blog.isnotworking.com/2007/05/api-design-guidelines.html

Bill Venners wrote several articles on object-oriented API design best practices in Java for a book that he was working on. This is a work in progress, and obviously focused on the Java language, but there are some interesting nuggets of information in there, such as maintaining a semantic contract, bundling services, and keeping your interface simple and focused. It appears that the book was never completed, however.

• http://www.artima.com/interfacedesign/

Joshua Bloch is the author of the book “Effective Java” and has a long history in the Java community. He gave an excellent talk on API design in 2007 called “How to Design a Good API and Why it Matters”. While this is focused on Java, Bloch covers many generic principles of API design that are just as applicable to C++ API development, such as class design, method design, exception design, and refactoring API designs. This slide set is well worth your time reading.

• http://www.scribd.com/doc/33655/How-to-Design-a-Good-API-and-Why-it-Matters
• http://www.cincomsmalltalk.com/blog/blogView?showComments=true&entry=3258158706

Jaroslav Tulach wrote the book “Practical API Design: Confessions of a Java Framework Architect.” Jaroslav also maintains a website to support the book. This site includes lots of tips on API design that, while focused on Java, still offer general insights for C++ engineers working on API tasks. His site also provides a Java source code download for many of the examples in his book.

• http://wiki.apidesign.org/

You can also read a review of Tulach’s book here:

• http://lambda-the-ultimate.org/node/3067