API Platform & Lifecycle · Governance and Quality
Detecting Breaking Changes in CI
Compare specs automatically and stop accidental breaks.
Most API breakages are accidental: a renamed field, a newly required parameter, a narrowed enum. Tools like oasdiff (OpenAPI), buf breaking (Protobuf) and schema registries (GraphQL, Avro) compare the proposed contract with the published one and classify changes. Fail CI on breaking changes unless explicitly approved with a versioning/deprecation plan, and attach the human-readable changelog to the PR.
Common change classifications
| Change | Breaking? | Why |
|---|---|---|
| Remove endpoint / field | Yes | Clients rely on it |
| Add required request field/param | Yes | Old clients don't send it |
| Narrow enum / tighten validation | Yes | Previously valid input rejected |
| Add response enum value | Potentially | Strict clients may crash |
| Add optional field / endpoint | No | Additive |
| Change field type or format | Yes | Parsing breaks |
# GitHub Actions step
- name: Check for breaking changes
run: |
git show origin/main:api/openapi.yaml > /tmp/base.yaml
oasdiff breaking /tmp/base.yaml api/openapi.yaml --fail-on ERR
oasdiff changelog /tmp/base.yaml api/openapi.yaml --format markdown >> $GITHUB_STEP_SUMMARY
# Protobuf
- run: buf breaking --against ".git#branch=main"
Common pitfalls
- Checking only paths, not schemas.
- Treating 'potentially breaking' as safe without telling clients to be tolerant.
- Overriding the check without a migration plan.
Key points
- oasdiff / buf / registries in CI
- Block breaking changes by default
- Generate changelogs automatically
Further reading: oasdiff
Practice questions
Why is tightening validation (e.g., shorter maxLength) a breaking change?
Answer
Requests that were previously valid start failing for existing clients.
What should happen when a breaking change is truly necessary?
Answer
Introduce it in a new version or behind an opt-in, keep the old behavior running, announce deprecation with dates (Deprecation/Sunset headers), and track migration per client.
Open in the app to mark lessons complete, take notes and track your progress.