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.
API Diff provides an extensible set of “Analyzers” that provide different methods for comparing source files. These include:
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.
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.