What Is API Diff?

API Diff is a program that lets you find all changes between different versions of an Application Programming Interface (API). You can use it for open-source, commercial, or in-house API projects.

An API is a software interface you provide to your clients, normally as a set of header files (.h or .hpp files) and library files (.dll, .so, or .dylib files) in the case of C and C++. Changes to an API can break your clients programs, so it’s important to inform them exactly what changed between each version of your interface. API Diff lets you automate this task by documenting every public code change in your API so that your clients know exactly what’s different.

Flexible Architecture

API Diff provides an extensible set of “Analyzers” that provide different methods for comparing source files. These include:

C/C++ Analyzer: Parses C and C++ statements and provide context-sensitive descriptions of all API changes. The parser supports C++98, C++03, and even the new C++0x standard. Comments Analyzer: Parses all source code comments and tells you which ones have changed. This can be used to review documentation changes before a release. Text Analyzer: A plain-text difference analyzer that essentially performs the same function as the Unix diff(3) command. This can be used to analyze APIs written in languages not directly supported by API Diff, such as Java, C#, Python, or Objective-C.

Combining a Diff Engine and a Parser

By using a C++ parser to compare C/C++ header files, API Diff can produce higher quality results than a simple text compare. For example, it can tell you that the type of a function parameter has changed, or that a class has added a new base class. It is also impervious to changes in the order of statements, whitespace differences, or comments. Furthermore, certain code changes do not affect the API, such as changing the name of a function argument.

For example, take a look at the results that API Diff produces on the following C++ source code example.

You should notice the following features:

• API Diff knows that the mStack data member is implicitly private in the left-hand file, so it knows that it has not changed in the right-hand file, even though it has moved position in the file and has been added to an explicit private: block.
• The IsEmpty() function has been declared as const in the right-hand file, and API Diff describes this interface change for you.
• The order of the IntStack, DoubleStack, and StringStack typedefs has changed in the right-hand file, but API Diff knows that this is not a significant change.
• Similarly, the name val has been provided for the Push() function’s argument in the right-hand version, but this does not affect client code and so is not flagged as a significant change.

Report Generation

In addition to letting you browse the diffs between two API versions interactively, API Diff will generate a summary report for the entire API. This specifies everything that changed between two versions of the API. This report can be saved to an HTML file so that you can share it with your clients. The report embeds mini diffs that can be selectively shown or hidden using JavaScript links. Here is a sample report generated by API Diff.

Integration with Automated Processes

You can use the basic functionality of API Diff for free. However, if you purchase a Professional license, you get additional command-line functionality to let API Diff better integrate with your development infrastructure.

For example, you could update your automated build script to produce a new API Diff report at the end of each compile step, so that your API documentation is always up to date. You can even customize the CSS for the report, to maintain your project’s visual style. Also, you can output a plain-text report that can be diff’d against a baseline version of the file so that you can issue an alert if a developer checks in a source code change that modifies the public API.

For details on the features of the various versions of API Diff, please refer to the Version Comparison page.