Skip to content
AppDues
Log in
Contact salesSign up

Tracking public API compatibility in Android and Kotlin

Public APIs are a contract with every team and developer who builds on them. This guide explains how to record that contract, spot unintended changes before release, and choose between two established tracking tools.

Treat the public surface as a contract

A library, SDK, or shared module exposes more than code: it exposes promises. Renaming a method, changing a parameter, or altering a class hierarchy can break consumers or force them to spend time migrating. Deliberate changes that are communicated are manageable; accidental ones create frustration because downstream teams discover them late. Kotlin makes vigilance especially important because public is the default visibility, so declarations can become part of the exposed surface without an explicit decision. Manual review alone is unreliable at scale, which is why an automated baseline is useful.

A practical baseline workflow

Start by deciding which modules publish a public surface. Record the current surface as a baseline file, then compare every later change against it. Review each difference and ask three questions: Was this exposure intentional? Does it break existing consumers? Has it been communicated and versioned appropriately? If the answer to the first question is no, tighten visibility or mark the declaration as non-public before it becomes a dependency for others. Keep the baseline under version control so reviewers can see surface changes in the same diff as the code that caused them.

Binary Compatibility Validator for Kotlin libraries

JetBrains' Binary Compatibility Validator is a Kotlin Gradle plugin that snapshots the public API and compares it with a recorded baseline. After applying it to a library module, run the dump task to create an .api file in the module's api directory, then inspect that file to understand the current surface. The check task builds the project and fails when the live surface differs from the baseline; because it joins the check lifecycle, it also runs during build and check executions. Configuration can exclude sub-projects, fully qualified classes, and annotations that mark effectively private API as non-public. The protected module code0001 shows the plugin setup, code0002 shows the apiValidation configuration, and code0003 and code0004 cover the dump task and baseline format.

Metalava when flavors or JVM flexibility matter

Metalava, developed by Google and used across Android and AndroidX, is a metadata generator for JVM-based projects, including non-Android libraries. It can extract public APIs into signature files, generate stub API files, export source-level annotations to external annotation files, and diff versions to assess compatibility. A community Gradle plugin wraps the official tool for convenient use. Configuration can hide annotated elements, pass custom arguments, and exclude source sets such as tests. Generate a signature with the protected module code0007 task; for flavored modules, generate one per variant as shown in code0008, such as separate pro and demo release signatures. The resulting api.txt file sits in the library module root, and the check task in code0007's companion workflow verifies the live surface against it during build and check.

Choose the tool, then enforce it early

Choose Binary Compatibility Validator when a Kotlin library has no complex flavor configuration and you want a straightforward baseline and check. Choose Metalava when product flavors, variant-specific signatures, or broader JVM support are needed, since the validator does not support modules configured with product flavors. In both cases, fail fast: a local Git hook can run the check before a commit and, on failure, regenerate the baseline so the developer reviews the diff and retries. In CI, run the same check so a commit introducing incompatible changes cannot merge until resolved. Local hooks give immediate feedback; CI gives an authoritative gate that no one can bypass accidentally.

Release checklist

Before your next release, apply these steps: identify every module with a public surface; generate and commit a baseline; add the check to the check lifecycle; wire a Git hook for local feedback; and add the same check to CI. Review baseline diffs during code review with the same care as logic changes. Even teams that never publish an SDK benefit, because the baseline reveals classes and interfaces that other modules can reach and helps keep internal boundaries clean. A stable, well-defined surface is what makes a library dependable for the developers who build on it.

Choosing a compatibility tracker
Decision pointBinary Compatibility ValidatorMetalava
Best fitKotlin libraries without complex flavor configurationsModules with product flavors or JVM-based projects needing flexibility
Baseline artifact.api file in the module's api directoryapi.txt signature file in the library module root
Check taskapiCheck, included in the check lifecyclemetalavaCheckCompatibility, included in the check lifecycle
Variant handlingDoes not support product-flavor modulesCan generate per-flavor, per-build-type signatures
Extra capabilitiesExclusions for projects, classes, and non-public markersStub generation, external annotations, and version diffs

Comparison based on the capabilities described in the guide; verify current tool versions before adoption.

Frequently asked questions

Is every public API change a problem?

No. A deliberate, communicated change can be acceptable. The risk is an unnoticed change that breaks downstream code or forces unplanned migration work.

Which tool fits a module with product flavors?

Binary Compatibility Validator is presented for Kotlin libraries without complex flavor setups. Metalava is presented as more flexible when product flavors or JVM-based projects need variant-specific tracking.

Why run the check in CI instead of only locally?

Both check tasks are described as part of the check lifecycle, so build and check runs validate the public API. That makes them suitable for CI enforcement.

Can this help if we do not publish an SDK?

Yes. In a multi-module project the same tracking can show which classes and interfaces are publicly reachable from other modules, helping teams keep internal boundaries deliberate.

\/\/ libs.versions.toml
[plugins]
kotlinx-binaryCompatibilityValidator = { id = "org.jetbrains.kotlinx.binary-compatibility-validator", version = "0.17.0" }

\/\/ root build.gradle.kts
plugins {
 alias(libs.plugins.kotlinx.binaryCompatibilityValidator) apply false 
}

\/\/ library module's build.gradle.kts
plugins {
 alias(libs.plugins.kotlinx.binaryCompatibilityValidator) 
}
\/\/ libs.versions.toml
[plugins]
metalava = { id = "me.tylerbwong.gradle.metalava", version = "0.4.0-alpha03" }

\/\/ root build.gradle.kts
plugins {
 alias(libs.plugins.metalava) apply false 
}

\/\/ library module's build.gradle.kts
plugins {
 alias(libs.plugins.metalava) 
}