All posts

Did the API Change This Week? Spotting Breaking Changes in Real Diffs

The integrator's weekly question: where breaking changes hide when the changelog says nothing, and how to answer from the real diffs.

Yes or no — and the only source that answers reliably is neither the changelog nor the release notes: it is the set of diffs the API's code actually received over the last seven days. An announced breaking change is the exception; most are born while fixing something else, and only the modified code keeps a record.

The question is not theoretical. It lands every week in the inbox of any team that exposes an API: asked by an integrator before upgrading, by a customer whose sync script just failed, or by an AI agent that needs to know whether the answer it is about to give is still true.

Why integrators ask this every week

A breaking change: any modification that forces a consumer of the API to change their own code to keep working. A renamed or removed field, a changed type, a different default value, tightened validation, a retired endpoint: the shape varies, the effect is the same.

Illustrative example: a team built its accounting sync on GET /invoices and reads the customer_id field. One Tuesday, the export stops matching payments. Nothing failed on the API side (the endpoint returns 200), but the field is now called client_id, renamed in passing during a naming harmonization. That week's changelog announces a new settings page.

An integrator who lives through this once changes behavior. Before every upgrade they run the same list: did the API change this week? Does anything break? Since which version? And they need an answer backed by the code, not by the communication around it.

Where breaking changes live: what each source sees

The table below sums up the gap. On the left, ordinary breaking changes (all illustrative); in the middle, what the source integrators read today says about them; on the right, what the diff says.

The changeWhat the changelog saysWhat the diff says
customer_id renamed to client_idNothing: the PR was called "naming cleanup"The serializer line where the field changes name
An amount goes from integer (cents) to decimal string"Billing improvements"The type change in the model and the added conversion
country becomes required on creationNothing: it shipped as a bug fixThe validation rule added to the controller
Default sort moves from created_at to updated_atNothing: side effect of a pagination fixThe modified sort clause in the query
GET /v1/reports removedAnnounced… three weeks after the effective removalThe deleted route, dated by its commit

The middle column is not a caricature: a changelog contains what someone decided to write in it. That is its job. The right column contains everything, including what the commit's author never perceived as breaking. When the question is "does anything break?", only the right column is authoritative.

Ask the code, get a sourced answer

Answering from diffs does not mean reading diffs yourself. That is what a product expert plugged into the repository is for: you ask in plain language ("did the API change this week?") and the answer comes back sourced: the endpoints touched, the commit carrying each change, and the line between what breaks and what merely adds.

That is what DeployIt does: it reads the real code (resynced on every push), the git history (commits and diffs) and the customer's data through its own MCP servers, and checks the code before asserting anything. The answer cites the customer_id rename even though the commit was called "naming cleanup", because it comes from the modification itself. And since the expert is exposed as an MCP server, the same question can be asked by a human in a chat or by your integrator's AI agent, at the moment it needs it.

The weekly question is just one window setting. "Since v2.3", "between August 12 and 26", "since my last upgrade": it is the same query over the history, bounded differently. It belongs to the family of "what changed in the product this week?", and the API variant is its most demanding member: here, an incomplete answer is paid for in someone else's production.

Ready to see what your team shipped?

"We handle this with the OpenAPI spec and versioning"

Many well-tooled teams answer: our OpenAPI spec is the source of truth, a spec-diff tool runs in CI, and semantic versioning announces the breaks. Keep that system. A spec kept current and diffed on every PR catches declared contract breaks, and it is the best team discipline there is.

Its blind spots are well known. A changed default, validation tightened in a controller, or a modified sort clause never show up in a spec diff: the spec describes the shape of the contract, not the behavior of the code implementing it. Three of the five rows in the table above are invisible to an OpenAPI diff. DeployIt's answers come from the code's diffs: they cover those breaks too, and they hold when the commit is called "wip".

The other limit is access. The spec and the official GitHub MCP server serve whoever has repository credentials; your integrators don't have any, and never will. An answer channel serves them without opening anything in the repository.

And DeployIt itself — what does it see of the repository?

A fair question for an API whose code is private. The footprint is narrow and verifiable: read-only GitHub connection, one server per project, revocable at any time. Answers are sourced from commits and diffs, with no raw source ever returned: your integrator learns that customer_id became client_id; they never read your serializer. The code never leaves the repository.

Three frequent questions

Do you need an OpenAPI spec for this to work? None is required. Answers come from the code and its history; if a spec lives in the repository, its changes are read like everything else.

Does this replace the changelog? Rather the opposite: it complements it, and can feed it. A changelog generated from git history is a published view of the same source; the question asked to the expert covers what the view left out.

Who asks the question in practice? Your integrators and their agents, your own support when a ticket smells like a breaking change, and your team before writing the upgrade note. All of them query the same source.

An answer backed by the code

"Did the API change this week?" deserves better than a changelog read cross-checked against the team's memory. The answer already exists in the diffs, dated and attributed. It just has to be made queryable.

DeployIt's MCP server is in early access / design partner program: if your integrators ask you this question faster than you can answer it, the program is open. DeployIt is free during early access; paid plans arrive in January 2027.

Ready to see what your team shipped?

Continue reading