• Increase font size
  • Default font size
  • Decrease font size

Table of Contents

The progression of chapters in this book roughly follows the standard evolution of an API, from initial design choices, through implementation decisions, versioning, documentation, and testing. The book also includes details on more advanced topics, such as creating scripting and plugin interfaces for your C++ APIs, as well as covering details on how to create static and shared libraries for your API implementation.

Foreword

Preface

Acknowledgments

Introduction

The Introduction chapter defines what an Application Programming Interface (API) is with various examples and describes how an API is represented in C++. This chapter details the difference between API development and standard application development as well as enumerating the pros and cons of APIs in software development. It then illustrates the various layers of APIs that a modern application is built upon, with specific reference to a large open source client/server program. The relationship of the terms API and SDK is explained, as is the relationship between APIs, file formats, and network protocols.

What Are APIs?

Contracts and Contractors

APIs in C++

What’s Different about API Design?

Why Should You Use APIs?

More Robust Code

Code Reuse

Parallel Development

When Should You Avoid APIs?

API Examples

Layers of APIs

A Real-Life Example

File Formats and Network Protocols

About This Book

Qualities

The Qualities chapter enumerates the set of language-neutral qualities that define a good API. This includes providing a good abstraction for the problem being solved and hiding implementation details through a combination of physical and logical hiding techniques. The quality of minimal completeness means that an API should be as small as possible but no smaller. An API should also be easy to use, which includes facets such as being discoverable, difficult to misuse, consistent, orthogonal, platform independent, and making appropriate use of smart pointers such as shared pointers, weak pointers, and scoped pointers. Robust API designs tend to be loosely coupled. Therefore, the term coupling is defined and several techniques are provided to reduce coupling in your APIs. Finally, it is noted that a good API should offer a stable interface that is well documented and regression tested.

Model the Problem Domain

Provide a Good Abstraction

Model the Key Objects

Hide Implementation Details

Physical Hiding: Declaration versus Definition

Logical Hiding: Encapsulation

Hide Member Variables

Hide Implementation Methods

Hide Implementation Classes

Minimally Complete

Don’t Over Promise

Add Virtual Functions Judiciously

Convenience APIs

Easy to Use

Discoverable

Difficult to Misuse

Consistent

Orthogonal

Robust Resource Allocation

Platform Independent

Loosely coupled

Coupling by Name Only

Reducing Class Coupling

Intentional Redundancy

Manager Classes

Callbacks, Observers, and Notifications

Stable, Documented, and Tested

Patterns

Design patterns are general solutions to common software design problems. This chapter provides details for various design patterns and C++ idioms that are particularly relevant to API development. This includes the pimpl idiom, which provides a way to hide all internal details from your public header files. The Singleton pattern provides access to global state. Its implementation in C++ is rather tricky so Singleton best practices are discussed, including initialization and thread safety issues. The Factory Method pattern makes up for several limitations of C++ constructors and can be used to hide implementation details for derived classes. Then various patterns are discussed for wrapping a new API on top of an incompatible or legacy interface. These include the Proxy, Adapter, and Façade patterns. Finally, the Observer pattern is covered as a way to reduce coupling between otherwise unrelated classes.
[Download PDF]

Pimpl Idiom

Using Pimpl

Copy Semantics

Pimpl and Scoped Pointers

Advantages of Pimpl

Disadvantages of Pimpl

Opaque Pointers in C

Singleton

Implementing Singletons in C++

Making Singletons Thread Safe

Singleton versus Dependency Injection

Singleton versus Monostate

Singleton versus Session State

Factory Methods

Abstract Base Classes

Simple Factory Example

Extensible Factory Example

API Wrapping Patterns

The Proxy Pattern

The Adapter Pattern

The Façade Pattern

Observer Pattern

Model–View–Controller

Implementing the Observer Pattern

Push versus Pull Observers

Design

The Design chapter begins with a cautionary tale of how software systems can accrue technical debt and eventually decay without good initial designs that are maintained as the software evolves. Subsequently, functional requirement gathering is discussed, including advice on how best to collect and maintain these requirements. The complementary methods of use case modeling and user story creation are also described. Then the topic of how to approach the design of an API is covered in detail, breaking this process up into high-level architecture design and detailed class design. This proceeds all the way down to the level of function and parameter design, as well as error handling techniques such as error codes and exceptions.

A Case for Good Design

Accruing Technical Debt

Paying Back the Debt

Design for the Long Term

Gathering Functional Requirements

What are Functional Requirements?

Example Functional Requirements

Maintaining the Requirements

Creating Use Cases

Developing Use Cases

Use Case Templates

Writing Good Use Cases

Requirements and Agile Development

Elements of API Design

Architecture Design

Developing an Architecture

Architecture Constraints

Identifying the Major Abstractions

Inventing the Key Objects

Architectural Patterns

Communicating the Architecture

Class Design

Object-Oriented Concepts

Class Design Options

Using Inheritance

Liskov Substitution Principle

The Open/Closed Principle

The Law of Demeter

Class Naming

Function Design

Function Design Options

Function Naming

Function Parameters

Error Handling

Styles

There are several different API styles that can be used to implement any given design. This chapter covers four different programming styles available to C++ developers and describes the pros and cons of each method. These include the use of a flat C API, without any C++ features such as classes, namespaces, or references; object-oriented C++ APIs, which can make use of inheritance, encapsulation, and polymorphism; template-based APIs, which allow functions and data structures to be written in terms of generic types; and data-driven APIs, which map well to web service APIs and support data-driven testing.

Flat C APIs

ANSI C Features

Benefits of an ANSI C API

Writing an API in ANSI C

Calling C Functions from C++

Case Study: FMOD C API

Object-Oriented C++ APIs

Benefits of Object-Oriented API

Case Study: FMOD C++ API

Template-Based APIs

An Example Template-Based API

Templates versus Macros

Advantages of Template-Based APIs

Disadvantages of Template-Based APIs

Data-Driven APIs

Data-Driven Web Services

Advantages of Data-Driven APIs

Disadvantages of Data-Driven APIs

Supporting Variant Argument Lists

Case Study: FMOD Data-Driven API

C++ Usage

This chapter deals with C++ language specific features that can affect API design. This includes using namespaces, either via a consistent prefix for all API symbols or the C++ namespace keyword. The topic of how to declare constructors and assignment operators correctly is then covered, including the rule of “The Big Three.” Const correctness issues are then covered, including method, parameter, and return value const correctness. Template API issues are covered, such as implicit versus explicit instantiation and best practices for structuring template header files. The section on operator overloading describes how to define operators in the most robust fashion and how to decide whether an operator should be a member or free function. The use of default arguments is presented as one way to make backward compatible API changes, though sometimes overloaded functions provide a better solution. The topic of symbol exporting is also explained, in particular the use of __declspec attributes for exposing symbols in a dynamic library on Windows. Finally, the use of good coding conventions is advocated and an example framework for such a document is provided.

Namespaces

Constructors and Assignment

Controlling Compiler-Generated Functions

Defining Constructors and Assignment

The Explicit Keyword

Const Correctness

Method Const Correctness

Parameter Const Correctness

Return Value Const Correctness

Templates

Template Terminology

Implicit Instantiation API Design

Explicit Instantiation API Design

Operator Overloading

Overloadable Operators

Free Operators versus Member Operators

Adding Operators to a Class

Operator Syntax

Conversion Operators

Function Parameters

Pointer versus Reference Parameters

Default Arguments

Avoid #define for Constants

Avoid Using Friends

Exporting Symbols

Coding Conventions

Performance

This chapter covers C++ API features that can impact the performance of your code. In general, you should not warp your API to achieve high performance: always measure performance and target any optimizations at actual bottlenecks. The performance increases of passing arguments as const references and of reducing your #include dependencies are analyzed. It’s shown how naive constant declarations can add weight to your classes, and it’s explained why using initialization lists is a good idea. The chapter also deals with memory optimizations so that your API maps well to modern CPU caching strategies, including variable clustering, bit fields, unions, and size-based types. The use of inlining can improve performance at the cost of exposing internal details, while the technique of copy on write provides a way to define large objects that are efficient to pass around by value. Finally, a survey is presented of performance profiling tools, including time, memory, and multithreading profilers.

Pass Input Arguments by Const Reference

Minimize #include Dependencies

Avoid "Winnebago" Headers

Forward Declarations

Explicit Include Guards

Declaring Constants

The New constexpr Keyword

Initialization Lists

Memory Optimization

Don’t Inline Until You Need To

Copy on Write

Iterating over Elements

Iterators

Random Access

Array References

Performance Analysis

Time-Based Analysis

Memory-Based Analysis

Multithreading Analysis

Versioning

The Versioning chapter deals with the important topic of change management and control. This begins by discussing the relevance of version numbers and introducing an example Version API, to let clients query the current version and feature set for an API. The life cycle of a typical API is then described, including pre-release, release, maintenance, completion, and deprecation. The various terms for backward and forward compatibility are defined, including functional compatibility, source compatibility, and binary compatibility. The important issue of how you can make changes to an API while still maintaining backward compatibility is discussed, including how to make API changes such as adding, changing, deprecating, and removing functionality. Finally, the importance and implementation of API reviews are presented.

Version Numbers

Version Number Significance

Esoteric Numbering Schemes

Creating a Version API

Software Branching Strategies

Branching Strategies

Branching Policies

APIs and Parallel Branches

File Formats and Parallel Products

Life Cycle of an API

Levels of Compatibility

Backward Compatibility

Functional Compatibility

Source Compatibility

Binary Compatibility

Forward Compatibility

How to Maintain Backward Compatibility

Adding Functionality

Changing Functionality

Deprecating Functionality

Removing Functionality

API Reviews

The Purpose of API Reviews

Pre-Release API Reviews

Pre-Commit API Reviews

Documentation

Well-written documentation is a critical element of an API. It describes what an API does and how it behaves, such as defining units for parameters, error conditions, or thrown exceptions. For behavior-only API changes, documentation is the only way to communicate a change to the API. Documentation is also necessary to communicate an interface’s contract when using contract programming. This chapter provides a checklist for what you should document and also details the various types of documentation that you can produce, including automated API documentation, overview documentation, code samples, tutorials, release notes, and license information. A large part of the chapter is dedicated to the effective use of Doxygen as a way to create API documentation automatically.

Reasons to Write Documentation

Defining Behavior

Documenting the Interface’s Contract

Communicating Behavioral Changes

What to Document

Types of Documentation

Automated API Documentation

Overview Documentation

Examples and Tutorials

Release Notes

License Information

Documentation Usability

Using Doxygen

The Configuration File

Comment Style and Commands

API Comments

File Comments

Class Comments

Method Comments

Enum Comments

Sample Header with Documentation

Testing

Automated testing is one of the most important activities you can invest in to ensure that API changes don’t break your clients’ programs. This chapter starts off by presenting the case for writing tests and then categorizes the various types of testing you can perform on an API, including white box testing, black box testing, and gray box testing, as well as unit testing, integration testing, and performance testing. It then covers how to write good tests by detailing the qualities of a good test, what to test, how to focus your testing effort, and how to work effectively with a QA team. The next topic looks at how you can write code that is more amenable to testing. This covers techniques such as test-driven development (TDD), stub objects and mock objects, how to test private code, proper use of assertions, contract programming, and internationalization issues. In the final section, various automated testing tools are presented, such as a range of test harnesses, code coverage tools, bug tracking systems, and continuous build systems.

Reasons to Write Tests

Types of API Testing

Unit Testing

Integration Testing

Performance Testing

Writing Good Tests

Qualities of a Good Test

What to Test

Focusing the Testing Effort

Working with QA

Writing Testable Code

Test-Driven Development

Stub and Mock Objects

Testing Private Code

Using Assertions

Contract Programming

Record and Playback Functionality

Supporting Internationalization

Automated Testing Tools

Test Harnesses

Code Coverage

Bug Tracking

Continuous Build System

Scripting

The Scripting chapter covers the advanced topic of how to expose your C++ API through a scripting language, such as Python, Ruby, Lua, Tcl, or Perl. This begins by explaining why you may want to do this and the issues that you will face in doing so, such as cross-language compatibility issues. The range of script binding technologies is presented, including Boost Python, Simplified Wrapper and Interface Generator (SWIG), Python-SIP, COM Automation, and CORBA. The remainder of the chapter provides practical instruction on how to add Python bindings using Boost Python and Ruby bindings using SWIG. In each case, specifics are covered such as how to expose a class hierarchy, define constructors, support inheritance, use language specific features such as properties in Python, and how to achieve cross-language polymorphism.

Adding Script Bindings

Extending versus Embedding

Advantages of Scripting

Language Compatibility Issues

Crossing the Language Barrier

Script Wrapping Technologies

Boost Python

SWIG

Python-SIP

COM Automation

CORBA

Adding Python Bindings with Boost Python

Building Boost Python

Wrapping a C++ API with Boost Python

Constructors

Extending the Python API

Inheritance in C++

Cross-Language Polymorphism

Supporting Iterators

Putting It All Together

Adding Ruby Bindings with SWIG

Wrapping a C++ API with SWIG

Tuning the Ruby API

Constructors

Extending the Ruby API

Inheritance in C++

Cross-Language Polymorphism

Putting It All Together

Extensibility

Extensibility is an important aspect of API design as it lets users expand the base functionality without requiring you to change the API. The bulk of this chapter deals with how to create a Plugin API, i.e., a way for users to extend the functionality of your API in defined ways by creating dynamic libraries that are discovered and loaded at run time. This deals with how to create stable C++ interfaces and covers the entire architecture, including the plugin API itself, the plugin manager, and example plugins. The chapter also covers other ways to extend an API, such as through inheritance, with a specific example of the Visitor design pattern. It also describes extensibility via templates, where the concept of policy-based templates and the curiously recurring template pattern (CRTP) are presented.

Extending via Plugins

Plugin Model Overview

Plugin System Design Issues

Implementing Plugins in C++

The Plugin API

An Example Plugin

The Plugin Manager

Plugin Versioning

Extending via Inheritance

Adding Functionality

Modifying Functionality

Inheritance and the STL

Inheritance and Enums

The Visitor Pattern

Prohibiting Subclassing

Extending via Templates

Policy-Based Templates

The Curiously Recurring Template Pattern

Appendix A: Libraries

APIs are implemented and distributed as static or dynamic libraries, such as Dynamic Link Libraries (DLLs) on Windows. This chapter describes the difference between static and dynamic libraries, the pros and cons of each, as well as covering the use of dynamic libraries to create plugins. The bulk of the chapter focuses on how to create libraries on Windows, Linux, and Mac OS X. This addresses issues such as exporting symbols, DLL entry points; how to use Microsoft Visual Studio, XCode, and the GNU C++ compiler; using frameworks on the Mac; useful utilities to analyze library files such as libtool, nm, ldd, otool, tasklist.exe, and dlister.exe; and how to write code to load plugins at run time.

Static versus Dynamic Libraries

Static Libraries

Dynamic Libraries

Dynamic Libraries as Plugins

Libraries on Windows

Importing and Exporting Functions

The DLL Entry Point

Creating Libraries on Window

Useful Windows Utilities

Loading Plugins on Windows

Libraries on Linux

Creating Static Libraries on Unix

Creating Dynamic Libraries on Unix

Shared Library Entry Points

Useful Linux Utilities

Loading Plugins on Unix

Finding Dynamic Libraries at Run Time

Libraries on Mac OS X

Creating Static Libraries on Mac OS X

Creating Dynamic Libraries on Mac OS X

Frameworks on Mac OS X

Finding Dynamic Libraries at Run Time

Bibliography

Index

ABOUT THIS SITE

An Application Programming Interface (API) provides a logical interface to a piece of software and hides its internal details. This website is dedicated to a book on designing APIs for C++ and includes articles and links on API development.
 

SOURCE CODE

The book is accompanied by a source code package that contains many of the examples in the text. Download it for free.
 

OTHER BOOKS

Dr. Reddy has also published a computer graphics book called Level of Detail for 3D Graphics. Check it out too!.
 
Copyright (c) 2017 Martin Reddy. All rights reserved. Login