Every API-first team eventually runs into some version of the same OpenAPI problem.
The spec is accurate when somebody writes it. A month later, it probably still looks accurate too, because most API changes aren't big breaking changes. They're small things.
Someone adds a field to a response. A backend change needs to get out quickly, so it gets made directly in the handler. The deadline was yesterday, everything still works, and updating the OpenAPI spec gets missed.
Nothing broke, so nobody notices.
At least not yet.
Then three weeks later a partner integration that's strict about the response gets a field it wasn't expecting. Now somebody is spending an afternoon digging through git blame in two different repos trying to figure out when tax_amount showed up on GET /v1/invoices/{id}, why it was added, and whether anybody actually needs to worry about it.
There are already good tools for API contract testing. Pact, Schemathesis-style CI checks, and similar tools can catch problems during testing and CI.
But that's not quite the problem we're interested in.
CI tells you what was true when the tests ran. It doesn't necessarily tell you that the API running in production has slowly drifted away from the contract everyone thinks it follows.
There are also plenty of "drift monitoring" tools in the ML world like Arize, WhyLabs, and Fiddler, but they're talking about a completely different kind of drift. They're watching models, outputs, and data distributions — not whether your production API still matches its OpenAPI contract.
What we couldn't find was something that handled the boring middle:
Watch a real API over time. Compare what it's actually doing against its own OpenAPI spec. When something changes, tell me whether I should actually care.
Not another giant YAML diff I have to sit there and interpret.
Something more like:
"This response has a new optional field. It's additive and probably safe."
Or:
"This endpoint stopped returning a required field. That's a breaking change and clients depending on it may fail."
That's the tool we've been sketching.
Give it an OpenAPI spec and a live base URL. It checks the API on a schedule and watches for drift. When it finds something, it explains what changed in plain English, whether it's likely breaking, why it matters, and what you probably need to do about it.
Then it puts that information somewhere you're already looking — a PR comment, Slack, email, whatever makes sense for the team.
We haven't built the full thing yet.
That's actually why I'm posting this now instead of showing up six months from now with a finished product and asking if anybody wants it.
If you've ever had the "wait... when did that get added?" moment with an API, I'd like to hear what happened.
What changed? How did you find it? And more importantly, what would have made catching it earlier actually useful instead of just creating another alert everyone ignores?
Early access: mattbridges.github.io/specdrift/
Top comments (0)