Getting Started · Contents
What counts as a breaking API change?
The six categories of change that break integrations, real examples from common providers, and how to catch them before production.
A breaking API change is any change to a provider's interface that can make code that worked yesterday fail, misbehave, or return different data today — without the calling code changing at all. The dangerous property is the asymmetry: nothing in your repository changes, so nothing in your build, tests, or code review catches it.
The six categories that break real integrations
- Removed or renamed endpoints: a path stops existing, or moves from /v1/charges to /v2/payments. Calls return 404 immediately.
- Removed response fields: a property your code reads is no longer returned. A strict parser throws; a loose one silently writes null into your database.
- New required parameters or headers: the call starts returning 400 because an argument you never sent is now mandatory.
- Authentication changes: an API key scheme is replaced by OAuth, a signing algorithm changes, or a header is renamed.
- API version retirement: a dated version keeps working until a shutdown date, then returns errors for everyone still on it.
- Semantic changes: the field still exists and the type is unchanged, but the meaning or unit changed — cents to dollars, a timestamp becoming a string, pagination defaulting differently.
The first five produce loud failures. The sixth produces silent corruption, which is why it is worth tracking alongside the obvious ones.
How providers actually ship these changes
Most large API providers publish changes continuously rather than on a release cadence, and each has its own mechanism for signalling risk:
- Stripe publishes a dated changelog and keeps old API versions alive per account, so the break arrives when an account upgrades its version or when an old version is retired.
- GitHub versions its REST API by date through the X-GitHub-Api-Version header and announces sunset dates in its changelog.
- OpenAI retires model snapshots on a published schedule, so a pinned model name can stop resolving even though your request shape never changed.
- Slack and Twilio change response payloads and auth requirements through their developer changelogs, often with a deprecation window rather than a hard cutover.
- AWS ships service-level release notes per product, which means one repository can depend on several independent change streams at once.
The common thread: the announcement is public, but it is published by the provider, in the provider's format, on the provider's schedule. Nobody on your team is subscribed to forty of them.
Why dependency updates do not cover it
Lockfile updates and Dependabot-style alerts track the SDK package you install. They do not track the remote service that package talks to. A pinned SDK version is entirely compatible with a server that has already removed the endpoint that SDK calls — which is why an integration can break with no dependency change, no commit, and no failing build.
How to catch breaking changes before production
- Pin the provider API version explicitly and record the retirement date somewhere a human will see it.
- Subscribe to every provider changelog your code touches — and route it to a place the on-call engineer actually reads.
- Add contract tests that assert the response fields you depend on, so a removed field fails a test instead of a customer request.
- Keep an inventory of which repositories call which endpoints, so an announcement can be turned into a list of files to change.
- Automate the matching step: static analysis of your code against the changelog feed, which is exactly what Breaklytix does.
How Breaklytix classifies a change
Breaklytix normalises each provider entry into a change type — breaking change, deprecation, API version change, endpoint change, request or response schema change, authentication change, SDK change, rate limit change or behaviour change — and assigns a severity. It then matches the entry against the providers, SDKs, environment variable names and endpoint strings detected in your repositories. An entry that matches produces an alert with the affected files and lines; an entry that does not match is still recorded, but it does not page anyone.
See the list of monitored providers and their official changelog sources, or read how the changelog pipeline classifies and deduplicates entries.
Is a deprecation the same as a breaking change?
No. A deprecation announces that something will stop working later; a breaking change is the point where it stops. Deprecations matter because they are the last warning before the break, so Breaklytix tracks both and treats a deprecation with a shutdown date as high priority.
Can a breaking change break code that does not use the changed endpoint?
Yes, indirectly. Shared SDKs, shared auth middleware and shared response parsers mean a change to one endpoint can affect call sites that never touched it. That is why impact is scored against the repository as a whole rather than a single file.
Do I need to upgrade my API version to be affected?
Not always. Versioned APIs only protect you while your pinned version is supported. When a provider retires that version, every account still on it is affected at the same time, regardless of what your code does.
How quickly does Breaklytix notice a change?
Provider sources are checked on the daily 06:00 UTC pipeline and deduplicated by a stable fingerprint. The delay between a provider publishing an entry and an alert being created is bounded by that daily cadence, not by a human reading changelogs. An on-demand repository scan runs immediately and reports what it finds.
What is the difference between a code break and an API error?
A code break is a static mismatch between your source and a changed interface, found before or after the change ships. An API error is a runtime signal that calls are currently failing. Breaklytix reports both, in Code Break Detection and Runtime Intelligence respectively.