How to Detect Breaking API Changes Before They Break Your App

A breaking API change doesn't always look like a breaking change.

It doesn't throw a 500. It doesn't trigger your error rate alerts. It doesn't fail your health checks. The endpoint returns 200, your monitoring stays green, and somewhere in your application, data is silently wrong.

This is how most API breakage actually happens in production — not as an obvious outage, but as a quiet structural change that propagates through your system until a user reports something weird.

This guide explains what breaking API changes look like in practice, how they happen, and — most importantly — how to detect them before users do.

What Counts as a "Breaking" API Change?

A breaking change is any API modification that causes existing client code to fail or produce incorrect results. The classic definition focuses on syntax-level breaks, but the real-world definition is broader:

Explicitly Breaking Changes

Silently Breaking Changes

These technically work but break your integration logic:

Example: The Stripe Incident Pattern

A payment integration reads response.payment_method.card.brand to display "Visa" or "Mastercard" in the checkout UI. The provider restructures their response — card moves inside a payment_details object.

The integration still works for 95% of requests (where card exists at the top level from cached data). But for new payment methods, response.payment_method.card is undefined. The brand display breaks silently. Users see a blank card brand but the payment still processes. The bug goes unnoticed for two weeks until a customer reports it.

The HTTP response was always 200. The error rate never moved.

Why Breaking Changes Go Undetected

Third-party APIs don't run your tests. When Stripe, Twilio, or OpenAI ships a change, your test suite doesn't run against their new API. You only find out when production traffic hits the new behavior.

Version pinning doesn't help with third-party APIs. You can pin your npm dependencies. You can't pin Stripe's live API. Third-party REST APIs change in place — all clients get the new behavior simultaneously.

Changelogs are easy to miss. API providers publish changelogs. Developers don't read them. Even when they do, it's easy to miss a change that "doesn't apply to you" — until it does.

Type systems don't protect you at runtime. TypeScript catches type errors at compile time against your type definitions. But if the API changes and your type definitions are stale, TypeScript is confident while your production code fails.

Monitoring tools check the wrong thing. Uptime monitoring checks status codes. APM tools track error rates and latency. Neither tells you that a field disappeared from a response.

How to Detect Breaking API Changes

Approach 1: Schema Drift Monitoring (Recommended)

Schema drift monitoring tools — like Rumbliq — continuously poll your API endpoints and compare live responses against a captured baseline. When the response structure changes, you get an alert with a precise diff.

This is the most practical approach for teams that consume third-party APIs, because:

How to set it up with Rumbliq:

  1. Add your API endpoint URL
  2. Configure authentication credentials (API key, Bearer token, OAuth) in the secure vault
  3. Rumbliq captures the response schema as your baseline
  4. Set your alert channels (Slack, email, webhook)
  5. You're done — Rumbliq polls on your configured schedule and alerts on any structural deviation

An alert looks like:

⚠️ Schema change detected: Stripe Payment Intent
Field removed: payment_method.card.brand (was string)
Field added: payment_method.payment_details.card.brand (string)

That's enough context to write the fix before any user sees the breakage.

Approach 2: Contract Testing

Contract testing tools (Pact, Dredd, OpenAPI-based) verify that your integration matches a defined contract. The contract specifies what the API should return, and tests fail when the live API deviates.

Strengths:

Limitations:

When to use: Internal service-to-service communication. Add contract tests to your CI pipeline for the APIs your services expose to other teams.

Approach 3: Synthetic Monitoring with Assertions

Synthetic monitoring runs scripted API tests on a schedule. You write assertions against response values, and the monitor alerts when assertions fail.

Strengths:

Limitations:

When to use: Critical user-facing workflows. Combine with schema drift monitoring for complete coverage.

Approach 4: Canary Deployments + Monitoring

Route a small percentage of production traffic through new code, monitor for error rate differences, and roll back if anomalies appear.

Strengths:

Limitations:

When to use: Your own service deployments. Not applicable for monitoring third-party APIs.

Building a Detection System: A Practical Approach

Here's how to build layered detection for breaking API changes across your dependencies:

Layer 1: Passive Schema Monitoring (Third-Party APIs)

Set up Rumbliq monitors for every external API your application calls in production. Prioritize:

Rumbliq's free tier covers 25 monitors — enough to instrument every critical integration for most teams.

Layer 2: Contract Tests in CI (Internal APIs)

For internal microservices, add Pact contract tests to your CI pipeline. When service A consumes service B's API, service A owns consumer-driven contracts that service B's CI must satisfy.

This prevents internal breaking changes from merging in the first place.

Layer 3: Synthetic Checks for Critical Paths

Write synthetic monitors for your five most critical user workflows:

Run these every 5 minutes from at least two geographic regions.

Layer 4: Alert Routing

Route alerts to the right people:

Real Examples of Breaking Changes in the Wild

OpenAI GPT API (2023): Changed the response structure for streaming completions. Teams that had built streaming UIs found their parsers breaking without a deprecation period. Schema drift monitoring would have caught this the moment the first check returned the new structure.

Stripe Elements (2022): Renamed several fields in the PaymentIntent response. The old fields continued to work for some time but were silently deprecated. Teams relying on the old fields shipped bugs when the graceful period ended.

Twilio Messaging API: Periodically updates status callback payloads. Teams processing webhook payloads for SMS delivery receipts have been caught by renamed status values.

AWS S3 (region-specific): AWS occasionally changes the format of error responses in specific regions. Integrations that parse S3 error XML can fail silently in certain regions while working in others.

The pattern is consistent: the change happens, the API returns 200, and your integration breaks silently. Detection requires looking at the structure of responses, not just whether they arrive.

Summary

Breaking API changes are inevitable — third-party providers change their APIs, and you don't control when or how. The question is whether you detect those changes before or after your users do.

The most practical approach for most teams:

  1. Add schema drift monitoring for every third-party API you consume. Rumbliq makes this fast to set up — no specs, no scripts, no maintenance overhead.
  2. Add contract tests to your CI pipeline for internal service-to-service APIs.
  3. Write synthetic checks for your most critical user-facing workflows.

With all three layers in place, you'll hear about breaking API changes from your monitoring stack — not from your users.

Related Posts

Start monitoring your APIs free → — 25 monitors, 3 sequences, no credit card required.