I just wrote this article on API design for Elsevier’s SciTech blog. It talks about the importance of hiding implementation details and covers information hiding techniques for C++, Objective-C, and Python, such as the pimpl idiom and class extensions. The article includes a discount code for 40% off my book, in case you’ve been waiting for the price to come down before buying it!  Check it out at:

• http://scitechconnect.elsevier.com/1-rule-api-design/

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/

Noah at 37 Signals wrote about API design for Web APIs. The key point he makes is about the need for strong documentation and having that documentation in an easy-to-search format. He then talks about authentication, advocating that an API offers multiple authentication schemes. Finally, he talks about building REST-like interfaces.

• http://37signals.com/svn/posts/3018-api-design-for-humans

Ferenc Mihaly has created a blog called The Amiable API dedicated to designing developer-friendly APIs. This web site grew out of a set of internal guidelines that Ferenc produced for his company and ultimately decided to publish in a blog format. Some of his recent posts include: Choosing memorable names, Striving for consistency, Keeping it simple, Considering the perspective of the caller, and Why developer-friendliness is central to API design.

• http://theamiableapi.com/

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

David Zeuthen has written a long and detailed article on many of the design issues that are faced when trying to write a plain C API. He deals with aspects such as library initialization, multithreading, error handling, versioning, and testing. It’s well worth a read if you are interested in writing a library in plain C (rather than C++). David’s collection of best practices is split into 5 parts, as follows:

• Part 1: Base libraries, Library init/shutdown, memory management, threads/processes
• Part 2: Event handling and the main loop, sync/async I/O
• Part 3: Modularity, namespaces, error handling, OO design
• Part 4: Helpers, daemons, and testing
• Part 5: API Design, documentation, and versioning

Michael DeHann wrote a blog article relating some of the things he’s learned about good API design. This includes advice such as programming with a view to the outsider, naming classes appropriately, figuring out how to make your code better through experiencing bad code, provide documentation that obviates the need for users to ask you how your code works, avoid redundant code, avoid extraneous conversions where possible, keep logic with the class that owns it, avoid adding complexity to your code through many options, and finally test your code but focus on functional end-to-end tests.

Many of these design tips are not new, but Michael provides a fresh perspective on them that I think is worth reading. Check out his post at:

• http://michaeldehaan.net/2011/04/29/class-api-design/

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.

Google’s Alex Martelli gave a speech at PyCon 2011 focusing on API anti-patterns, which he defines as counterproductive behaviors that are often systematically repeated. He states that the worst anti-pattern is not having any API at all, and the second worst is not having any design (an accidental API). Most of the talk is aimed at a process or design level, though a couple of specific code examples are given. For example, Martelli talks about the fact that a lot of software is overdesigned, but when you’re dealing with an API it’s actually good to spend a lot of up-front time thinking about future expansion and evolution before release. In terms of designing a good API he suggests thinking about 3 ways to implement your API: the common concepts will be the core functionality that should be in your API. He also suggests that you should use your own API as much as possible. Finally, he spends some time talking about choosing to do something one way, not two ways, i.e., taking a stand and making a decision. The talk is just over 40 mins and offers some great high-level insights into how to go about designing a good API, be it C++, Python, or Web-based.

• http://pycon.blip.tv/file/4878793/

Dan Webb wrote an article about API design where he suggests that you should first think about how you would like your interface to be used, before diving into details like class and function design. He argues that your API has to be simple and fun to use, providing the example of the Web-based jQuery API as an exemplar of this goal. I agree with Dan’s points: user-oriented issues such as the simplicity and usability of an API are often overlooked to the detriment of a library’s success. Dan also echos other suggestions that I make in “API Design for C++” about providing a simple interface for common operations but also enabling more complex operations with a more advanced underlying API.

• http://www.danwebb.net/2011/2/10/writing-a-new-library-sketch-it-out-first

The POSIX pthreads standard provides a flat C API for managing threads. Eli Bendersky wrote an article that highlighted many of the good API design techniques used in that API. For example, it is simple and orthogonal, consistent, employs logical naming, uses opaque types that hide internal details, and uses attribute objects to reducing function parameter lists. This article is a good read for those interested in examples of good C APIs.

• http://eli.thegreenplace.net/2010/04/05/pthreads-as-a-case-study-of-good-api-design/

Marsh Gardiner of Apigee recently gave a talk at Cloudstock 2010 in San Francisco entitled, “Your API Sucks: Why developers hang up and how to stop that”. While this talk is focused on the currently hot topic of Web-based APIs, Gardiner talks about a lot of general API design techniques. In particular, he urges API developers to focus on user experience and to remember that your API is a product and your developers are your customers. He states this involves putting yourself in your users shoes and giving them the information they need to succeed. Check out the 30-min audio recording of the talk and slideset at:

• http://blog.apigee.com/detail/api_design_for_developers/

In one of his regular ACM Queue articles, George Neville-Neil (a.k.a. Kode Vicious) responded to a question about API design for a database service. In this article, he points out some poor ways of implementing such an API, resulting in a “fat” API that can be difficult to use and promotes poor coding practices like copying/pasting code. He then goes on to suggest improvements to the design and provides some examples of file I/O APIs that he feels are well designed. Finally, he notes that API design is an iterative process that improves over time as you receive feedback from developers who actually use your interface.

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

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