As part of the Oracle lawsuit against Google, there is an interesting discussion going on about whether APIs can be copyright. Oracle argues that copyrighting an API is reasonable, claiming that APIs “contain many original and creative elements,” while Google notes that API design “is an art, not a science.” See Mike Masnick’s post on the topic here:

http://www.techdirt.com/articles/20110822/11242915616/side-show-oracle-google-patent-fight-are-apis-covered-copyright.shtml

My own point of view is that an API is a specification and does not exhibit any inherent behavior of itself; whereas an implementation that conforms to that specification has behavior and can involve intellectual property in terms of specific algorithms or implementation code. Moreover, an API is inherently public by definition – the point of creating an API is to allow other developers access to your implementation in a standardized way, and as such the API has to be public and open (such as via public header files in C++), versus a specific implementation that can be private and protected (such as the source files used to build a library file in C++).

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

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/

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

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

The Communications of the ACM published an article called “Version Aversion”, which discusses various approaches to using version numbers in a software project. Much of the discussion mirrors the content in my book, API Design for C++, including the use of major/minor/patch version triples, tips on when to bump each of these version numbers, and reference to more esoteric versioning schemes like the Windows operating system choice of Windows 95, Windows 98, Windows ME, Windows NT, Windows XP, etc. You’ll need access to the ACM Digital Library to read the article.

• http://portal.acm.org/citation.cfm?id=1831407.1831420

A unit test is a white-box testing technique that a developer performs. White-box means that you write the tests with knowledge of the implementation of the API. There are many frameworks out there that help you write, maintain, and run unit tests for your code. Most of these are based upon the J-Unit style of unit testing. Wikipedia offers a good categorization of unit test frameworks that are available for C and C++. See:

• http://en.wikipedia.org/wiki/List_of_unit_testing_frameworks#C
• http://en.wikipedia.org/wiki/List_of_unit_testing_frameworks#C.2B.2B

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

Andrei Alexandrescu published an excellent book called “Modern C++ Design.” In this book, he introduced the notion of policy-based templates as a way to provide highly-configurable solutions to various design patterns. He made the source code for these templates available via his Loki library, available at:

• http://sourceforge.net/projects/loki-lib/

DynObj is a C/C++ library for creating cross-compiler plugin libraries from Arne Steinarson. It’s based on a shared type information system and allows you to load binary plugins and to interact with them in type safe ways.

• http://dynobj.sourceforge.net/
• http://www.codeproject.com/KB/library/dynobj.aspx

The author notes the following potential uses of DynObj

1. A program working with sound can install additional effect filters while running.
2. A file manager can add plugins that handles new archive types.
3. Or it can add file popup menu handlers, or toolbar commands from plugins.
4. A text editor can add an editing mode (say Python editing) when the text editor is running.

Arne also provides a great background to the problem of creating cross-platform and cross-compiler plugins.