What is the cheapest thing I can do this week?

Three moves: subscribe to the changelogs of your critical providers and route them to a channel someone reads; add a scheduled contract test for your single most dangerous integration path; and start keeping dated response captures (HAR files or logged samples, values redacted) so the next incident has a before to diff against. None of this requires buying anything.

Should the check run in CI or in production?

Both, for different reasons. Production observation catches changes when they actually ship, on real traffic. A CI gate answers a different question: has anything drifted since the baselines this build was tested against, before you deploy on top of it. The pairing is what turns detection into prevention.

How do I avoid drowning in false positives?

Never diff raw responses. Reduce to structure (field names and types), baseline over multiple observations, and alert only on sustained displacement. Treat a first observation as a profile, not an alarm, and treat value changes as noise by construction. Every false page you send teaches the team to ignore the real one.

How to detect breaking changes in third-party APIs

Practical options for catching upstream API changes before production does: changelog watching, spec diffing, contract tests, structural traffic profiling, and CI gating. Including what you can build yourself.

The goal, stated precisely

You want to know that a third-party API's contract changed before the change becomes a production incident, with enough evidence to act: what changed, when, which of your code paths touch it. Background on why this class of failure is invisible to normal monitoring is in what is API drift and silent breaking changes; this page is the practical how.

The build-it-yourself ladder

Rung 1: watch what providers announce

Changelog RSS feeds, deprecation mailing lists, provider Discords, routed into a channel with an owner. Cost: an hour. Catches: announced changes. Misses: the unannounced class, which is the dangerous one. Do this regardless of anything else you adopt.

Rung 2: diff the spec, when there is one

If the provider publishes OpenAPI, snapshot it on a schedule and diff versions (oasdiff is the standard open tool); fail CI on breaking diffs. Cost: a day. Catches: spec-visible changes. Misses: everything the spec does not model, and every gap between the document and the live API.

Rung 3: probe the endpoints you fear most

A scheduled job calls your critical endpoints with known inputs and asserts the response shape: required fields present, types correct. Validate structure, never exact values. Cost: days, plus permanent upkeep. Catches: changes on the exact paths you probe. Misses: every path you did not write a probe for, and every shape your test account's data never produces.

Rung 4: profile your real traffic

The serious step: observe the responses your application actually receives, reduce each to structure at the edge (field names and types, values discarded immediately), baseline per operation, and alert on sustained displacement. This is the layer that catches unannounced changes on surfaces you never thought to probe, because production traffic is the most complete test suite you own. Building it well means solving three hard problems: anonymization at the edge that provably never stores values, temporal gating that separates drift from variance, and severity that reflects blast radius. This rung is where build-versus-buy gets decided honestly; the full landscape is compared in API drift monitoring: an honest guide.

Rung 5: gate deploys on it

Detection prevents repeat diagnosis; gating prevents the incident. A CI check that fails the build when a dependency's observed contract has drifted since your baselines turns upstream change from a 2am page into a red check on a pull request. This is also the point where drift tooling stops being a dashboard and becomes infrastructure.

What no single team can build

Everything above shares one ceiling: you learn about a change when your traffic meets it. The change itself usually shipped to everyone at once. A neutral network watching the same providers across many companies converts the first encounter anywhere into a warning everywhere, hours or days of lead time no solitary setup can produce. That cross-company layer is ShiftGraph's reason to exist: the same structure-only discipline, pooled. Its public seed, watching the API economy's common surfaces daily, is the Observatory.

Common questions

What is the cheapest thing I can do this week?: Three moves: subscribe to the changelogs of your critical providers and route them to a channel someone reads; add a scheduled contract test for your single most dangerous integration path; and start keeping dated response captures (HAR files or logged samples, values redacted) so the next incident has a before to diff against. None of this requires buying anything.
Should the check run in CI or in production?: Both, for different reasons. Production observation catches changes when they actually ship, on real traffic. A CI gate answers a different question: has anything drifted since the baselines this build was tested against, before you deploy on top of it. The pairing is what turns detection into prevention.
How do I avoid drowning in false positives?: Never diff raw responses. Reduce to structure (field names and types), baseline over multiple observations, and alert only on sustained displacement. Treat a first observation as a profile, not an alarm, and treat value changes as noise by construction. Every false page you send teaches the team to ignore the real one.