API Design for C++ by Martin Reddy
February 18, 2011
Publisher: Morgan Kaufmann
An API is defined as "reusable building blocks that allow modular pieces of functionality to be incorporated into end-user applications". It provides a logical interface for a client while hiding its implementation details. We can think of the API as an abstraction and a functional specification of a component it implements. The importance of well-defined interfaces is underlined by a fact that problems in interfaces are far more costly to fix than problems in the associated implementation. That's because APIs (and their interfaces) should remain backward compatible which implies a need for a change control process and automated regression testing. Also, a stable interface acts like a contract between two pieces of software. This allows multiple developers to work in parallel and call API's functions before they are even completed. Good documentation should also be delivered with an API.
Whenever you create a file format or client/server protocol, you should also provide an API to interoperate with them.
APIs promotes, among other things, code reuse. While there are many benefits of that (e.g., reduction of code duplication) you may encounter also some difficulties. For example, if you intend to reuse a given piece of code you may need to come up with a more general interface than you intended in order to encompass clients changing requirements.
There are also circumstances when it is better to avoid creating an API. For example, if the API is going to be used only in a single application it may not be worth an effort of planning, testing, documenting and supporting. On the other hand, you may consider creating your own API if existing APIs have some limitations such as license restrictions, not exact functionality you need, no source code, or poor documentation.