API compatibility checking
Diffs a public interface between the base and the change and reports breaking changes: removed endpoints, changed types, narrowed inputs.
Sub-techniques
3
| ID | Name | Description |
|---|---|---|
V1013.001 | HTTP API diff | Compare OpenAPI documents for breaking changes, and lint them for style. |
V1013.002 | Schema and protobuf compatibility | Wire-compatibility rules for protobuf, Avro or JSON Schema. |
V1013.003 | Library API diff | Compare the exported symbols and signatures of a package against its last release. |
Craft it
- Generate the interface description (OpenAPI, .proto, public symbols) in CI on both base and head.
- Fail on breaking differences unless the version is bumped or a label allows it.
- Publish the diff as a PR comment so reviewers see the contract change.
Reverse engineer it
Signs that a codebase already runs this technique, and where to read how it is configured.
- buf.yaml with a breaking section, oasdiff in CI, api-extractor.json.
- Semver checks in release workflows.
Open-source packages
7
- oasdiff oasdiff/oasdiff
- Spectral stoplightio/spectral
- Buf (buf breaking) bufbuild/buf
- Griffe (griffe check) mkdocstrings/griffe
- cargo-semver-checks obi1kenobi/cargo-semver-checks
- japicmp siom79/japicmp
- API Extractor (Rush Stack) microsoft/rushstack