Christopher Scaffidi wrote this ACM Crossroads article in 2006 about the usability of APIs. He presents four challenges of API design and presents various strategies to overcome these. The challenges are: 1) inadequate documentation, 2) insufficient orthogonality, 3) inappropriate abstractions, 4) incomplete assumptions. In summary, he states that three themes occur when designing a good API: make the problem smaller, use an approach that is only fast on average, and find an approximate solution.

• http://portal.acm.org/citation.cfm?id=1144363
• http://web.engr.oregonstate.edu/~cscaffid/papers/pr_20060601_api.pdf

Ivanka Majic conducted several interviews with developers about what makes a good API. The three basic categories that she came up with as a result are that an API should be designed well, should have good documentation, and good support.

Under the topic of great API design, Ivanka provides various quotes from her interviews that support the qualities of consistency, predictability, and learnability, as well as noting that a good API is easily extended and gets better over time.

In terms of API documentation, she states that there should be an overview to explain what the API does, that documentation should be concise and logical, use navigation to expose content, and offer tutorials to help developers starting from scratch.

• http://design.canonical.com/2010/12/so-you-want-to-provide-an-api-for-the-world-to-use/

Larry Garfield will present a talk called “Aphorisms of API Design” at the Dupalcon conference in Chicago, Mar 7-10 2011. Here is the description of the talk:

Code that talks only to itself is not useful to anyone. Code that enables other code magnifies its power 10-fold.

But how do we enable other code, and those who write it? What makes a module extensible? What is that vague extra something that turns merely extensible code into an API, a library, and a cornerstone of other systems? How do we harness that power for ourselves?

Let us examine the Aphorisms of Good API design, and the 8-Fold Path of API Nirvana.

This session goes beyond how to write modules well to cover the question of how to write modules that spawn other modules and innovation by Coding for the Future.

Intended audience:
Module developers who want to write not just good code but code other developers will want to use. Site builders and evaluators who want to know how to tell if a module is “doing it the right way”. Site Architects who want to know what modules are likely to be extensible in the future rather than evolutionary dead ends.

See: http://chicago2011.drupal.org/sessions/aphorisms-api-design

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

C. Lawrence Wenham compiled a great list of API design tips, including concepts such as naming, consistency, reducing complexity, avoiding side effects, and avoiding boolean arguments. He also advocates for designing an API from the point of view of the client, rather than choosing the solution that’s easier to implement (which is perhaps an obvious statement but still all too commonly violated). This is a concise yet thorough collection of important concepts to bear in mind when you’re designing an API. Well worth a read.

• http://sites.google.com/site/yacoset/Home/api-design-tips

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

Some of the original authors of the Design Patterns book recently gave an interview for InformIT, called “Design Patterns 15 Years Later: An Interview with Erich Gamma, Richard Helm, and Ralph Johnson”. This is an interesting retrospective on Design Patterns and their relevance today. It’s interesting to note that the only pattern they may not include today is the Singleton because, as Erich notes, it’s use is often a design smell.

• http://www.informit.com/articles/article.aspx?p=1404056

Brady Booch is chief scientist and fellow at IBM Research and is known for co-developing the Unified Modeling Language (UML). He has been doing a regular podcast for IEEE Software called “On Architecture”, where he discusses various topics on developing software architectures. These are more than general than API specific concerns, but it’s still a really interest set of podcasts for you to listen to.

• http://www.computer.org/portal/web/computingnow/onarchitecture

Mathieu Jacques wrote an article called “API Usability: Guidelines to improve your code’s easy of use.” This articles starts by defining the fundamentals of usability then proceeds to provide various usability guidelines such as good visibility, good conceptual model, good mapping, and good feedback.

• http://www.codeproject.com/KB/usability/APIUsabilityArticle.aspx

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/

Michi Henning wrote an article in ACM Queue called “API Design Matters” in which he suggests that changing APIs should be a criminal offense and that authors of poor APIs should be held accountable for their crimes. He notes that good APIs are hard to design and he presents some examples network and synchronization APIs that could be improved. He also calls for APIs to be documented before they are implemented.

• http://queue.acm.org/detail.cfm?id=1255422

Some comments on this article can be found here.

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

The Nokia Qt library provides a cross-platform application and UI framework for C++. It is often used to create user interfaces for programs that must run on several different platforms, but it also includes a large array of lower-level functionality, such as classes to handle threads, database access, regular expressions, networks, and XML.

Several of the Qt developers have written on the topic of good API design for C++. For example, Matthias Ettrich wrote an article on designing Qt-style C++ APIs that covers many good issues such as characteristics of good APIs, the boolean parameter trap, and the art of naming. See:

• http://doc.trolltech.com/qq/qq13-apis.html
• http://qt.gitorious.org/qt/pages/ApiDesignPrinciples

Also, Jasmin Blanchette wrote a document called “The Little Manual of API Design” that provides a similar treatment but with a bit more detail and covers more material on the design process and design guidelines. See:

• http://www.scribd.com/doc/15729315/The-Little-Manual-of-API-Design