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/

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

The next iteration of the C++ standard passed the ISO technical committee review earlier this year and is scheduled to be approved this fall. This version of the specification is now referred to as C++11 (a reference to the year it will be approved). Jim Humelsine recently sent me the following link that provides a neat table of the new features of C++11, along with the status of their implementation in the gcc compiler. This resource was put together by George Flanagin and provides a succinct overview of the new features of C++11 as well as a great reference for those interested in trying some of these out in their own code. As I describe in my book, many of these new features allow for better C++ API designs.

• http://www.georgeflanagin.com/c++11/c++11.features/

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/

This website presents an interactive architecture diagram of the Linux kernel. The diagram breaks the kernel into a grid of functionality and layers with the ability to pan and zoom the map. You can then click on a specific item to look it up in the Linux source code.

One of the problems of providing documentation for a large project such as the Linux kernel is how to make the information manageable to navigate. This interactive diagram is a great way to provide an overview of all the available APIs and gives developers a jumping off point into the API documentation (although in this case it is an index to the actual code, rather than a documentation index).

• http://www.makelinux.net/kernel_map.shtml

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

I recently came across this list of freely-available C++ libraries. The page hasn’t been updated for a few years, but it’s still a really good list of the different kinds of C++ APIs that are out there for you to use in your own applications.

The list is broken down into several categories, including: Generic, Script Integration, Text Manipulation, Threading, Signalling and Parallel-Programming, Numerical, Algorithmic and Crypto, Network and Web Programming, Multimedia, File Format, GUI, Device Access, Testing and Debugging, Database Engine/Interface, Science, and Financial.

• http://wikicompany.org/fs/c++.html

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

The NPAPI is a cross-platform plain-C plugin interface used by several web browsers to allow custom native-code to handle certain content types. It is used by Firefox, Chrome, Konqueror, and Opera, among others. When a browser encounters a content type that a plugin wants to handle, it loads that plugin, allocates a region of the web page for the plugin to control and then streams data to it so that the plugin can render the data as it sees fit.

Adobe’s Acrobat, Shockwave, Flash renderers are examples of plugins built against this plugin API.

The following web page provides various resources for using the NPAPI:

• https://developer.mozilla.org/En/Plugins

The Standard Template Library (STL) provides a collection of containers, iterators, algorithms, and functors for C++. This is perhaps the most famous and widely-used C++ API. It provides template-based containers such as std::string, std::vector, std::map, and std::set, which you can specialize with your own types (std::string is of course already specialized for characters). The STL is therefore a good place to look for an example of compile-time polymorphism in C++. The authoritative documentation is the STL programmer’s guide from SGI:

• http://www.sgi.com/tech/stl/

The Boost libraries are a collection of open-source libraries that extend the functionality of C++. Many of the Boost founders are active in the C++ standards committee and as a result several of the Boost libraries have been included in the new C++ ISO standard (C++0x), including smart pointers, function object binders, type traits, and tuples. You’d have to go a long way before you find better examples of modern C++ API design.

• http://www.boost.org/

You can also find a good overview of the Boost libraries on Wikipedia.

Intel provides the Threading Building Blocks (TBB) as an open-source library to make it easier to write multithreaded C++ code. This library offers some good examples of C++ API design, including the use of namespaces, templates, containers, iterators, and parallel programming patterns. The TBB library works for Windows, Mac OS X, and Linux.

• http://www.threadingbuildingblocks.org/documentation.php

Apache is a web server project that aims to maintain an open-source HTTP server for modern operating systems. One of its goals is to provide an extensible server, which it achieves through a C plugin interface that lets users add new “modules” to the core server. Apache’s module interface is therefore an example of a widely-used C/C++ plugin API. The following page provides details on the Apache module API, including tutorials, code examples, and reference documentation.

• http://modules.apache.org/reference.php