API version changes: preventing broken integrations
Most integrations do not fail loudly, they fail in silence. Build a routine that catches breakage from the deprecation notice through to cutover day.
Monday morning, and the marketing lead is reading the weekly summary. Web form submissions are not zero, just low. Everyone assumes it is a slow season. Eleven days later a prospect emails to ask why nobody responded to the form he filled in. The record is checked, and it is there. The integration is running, the error log is clean, the connection shows green. The only problem is that the form tool renamed its phone field in a routine version update. Records were created without a phone number, and the assignment rule that requires one quietly assigned none of them to anyone. Eleven days of inbound demand sat in a pool nobody was watching.
Most broken integrations look exactly like that: no error, no alarm, and a discovery weeks late. What follows covers why integrations break in silence, how providers signal versions, how long each type of breakage takes to surface, how to build an integration inventory, why deprecation notices reach the wrong person, what testing and cutover actually require, the defensive rules that belong on your side, the monitoring signals worth having, a rollback plan, and when not upgrading is the correct decision.
Why do integrations break in silence?
Breakage comes in three kinds, and they surface at wildly different speeds. Loud breakage is obvious: authentication is refused, an endpoint disappears, the connection returns an error. Annoying, but self-announcing. Silent breakage is when the interface still returns success while the content underneath has changed, so your system believes everything is fine. The third kind is delayed: a quota tightens, pagination behavior shifts, and data goes missing only at peak hours and only partially.
What makes silence dangerous is not the absence of an alarm; it is that the system keeps producing data. An empty field aggregates as zero in a report, a value whose meaning changed corrupts segmentation, a missing relationship hangs a record on the wrong customer. By the time anyone notices, there are two jobs instead of one: fix the integration, then clean up the data it polluted in the meantime. The second job almost always takes longer.
That is where the real cost sits. A broken integration loses less data than it loses trust. A report that was wrong once keeps getting questioned long after it is fixed; the team stops looking at the number and starts asking where the number came from. Whatever discipline you built on the assumption that automations are healthy reverts to manual checking after one silent failure.
How do providers signal versions?
Three patterns dominate. The first carries the version in the address, so a second version is published on its own path and you move when you are ready. The second is date-pinned versioning: your account is fixed to a date, and new behavior arrives only when you move that date forward. The third declares the version in a request header. Whatever the pattern, the thing that matters is knowing which version you are on — and most teams find that out for the first time when something breaks.
Then there is the case where the version number never changes but field-level deprecation is quietly under way. A provider first makes a field optional, then starts returning it empty, then removes it. Months can pass between those three steps, and none of them shows up in a version number. The compatibility promise in the contract does not help here, because the two sides define a breaking change differently: adding a required field is an addition to the provider and a break to whoever validates it on the other end.
What a version number tells you, and what it does not
Moving to a new major version gets planned like a one-off project, while the real risk accumulates inside the version you are already on. A new value appearing in a status list, a timestamp starting to arrive in a different time zone, a text field's length limit increasing — none of these changes the version number, and all three can break something on your side. The right question is what your code does when it meets a value it has never seen. If the answer is that it silently drops it, your first silent failure has already been written.
Types of breakage and how long they take to surface
Before planning any migration, it helps to see which kind of failure will find you and how fast. This distribution also tells you where alarms actually belong.
| Type of breakage | How it surfaces | Typical delay |
|---|---|---|
| Authentication refused | Error log, immediately | Hours |
| Endpoint removed | Error log, immediately | Hours |
| Field removed, returns empty | Reporting inconsistency | Weeks |
| Field meaning or format changed | Accumulation of wrong data | Weeks to months |
| Quota or rate limit tightened | Partial loss at peak hours | Days |
The first two rows are, in effect, good news: the system shouts at you. The money is lost in the middle two, precisely because nothing shouts. That is why monitoring investment belongs on the shape of the data rather than the error log; which signals to watch for connection health is laid out in our piece on integration monitoring.
No migration is plannable until you know what you have
In most companies the number of live integrations comfortably exceeds the answer you get when you ask. Alongside the three officially built connections sit an automation scenario spun up for one campaign, a spreadsheet sync a summer intern configured, and a form tool a marketer connected with a personal account. None of it is documented, and all of it can break on a version change.
- Connection name and direction: Which system feeds which, and whether the flow is one-way or two-way; impact analysis is impossible without direction.
- Version and endpoints in use: Which version you are on and which endpoints you call must be written down, because deprecation notices are issued per endpoint.
- Owner: Every connection needs a role as its owner rather than a person; ownership attached to an individual evaporates at the first resignation.
- Credential type and expiry: A static key or an authorization flow, and when it expires; an expired credential looks exactly like a version change from the outside.
- Business impact: What happens if this connection stops today; if the honest answer is nothing, the effort worth spending to preserve it is also nothing.
- Last successful run: The only objective evidence that a connection is alive — being configured is not the same as working.
- Manual fallback: How the work gets done if the connection is down for three days should be written in advance, not invented during the incident.
The line most often skipped is ownership. Connections tend to get built with one person's account, one person's email address and a key only that person knows. When they leave, the connection keeps running for a while and then dies quietly. Why credentials belong to the organization rather than an individual is covered in API keys and secure access management, and that is genuinely the first step in version management.
Who receives the notice?
Providers send deprecation notices to the technical contact address on the account. In most small companies that address is one person's work email, and a year later that person works somewhere else. The notice goes out, nobody reads it, the deadline passes. The fix is trivial and takes ten minutes: change the technical contact on every provider account to a durable group address, and route that address somewhere at least two people read.
The second point belongs to the buying stage. Contracts routinely carry an availability commitment; they almost never carry a deprecation-window commitment. In other words, the provider will tell you how many minutes of downtime it may have in a month, but not how much notice it owes you before switching off an interface. Asking that during evaluation is far cheaper than asking afterward; we open up the dependency side of it in vendor lock-in and data portability.
Testing: what a sandbox proves and what it does not
A provider's test environment proves the new version works. It does not prove it works on your data. Sandbox records are clean: every field populated, every date well formed, every string short. Your production data holds years of half-finished records, phone numbers entered two different ways, and required fields nobody ever filled in. What breaks during a migration is almost always that tail. How to set up a test and change-management environment is covered in sandbox and change management.
Acceptance criteria have to be concrete too. The most useful method is a comparison run: read the same set of records through the old and new versions and compare outputs field by field. The difference list will contain two kinds of entries — differences you expected and differences you cannot explain. Do the migration only when the second list is empty. How fields align between two systems is walked through in field mapping.
Writing defensively on your own side
The best protection against version changes is not the provider's discipline; it is how you read what arrives. Four rules cut off most breakage at the source. When an unknown field appears, do not crash — ignore it. When an expected field is missing, do not invent a default; reject the record and queue it, because an invented default is silent breakage by definition. Never assume a date or number format, parse it explicitly. And store the external system's identifier on your side so matching rests on identity rather than text.
The most dangerous state an integration can be in is not failing, but working incorrectly without failing.
A fifth rule concerns retries. When a request times out, most systems try again; if the other side actually processed the first one, you get a duplicate record. Attaching a unique identifier you generate to every request, and having the other side recognize it, ends that class of problem. The security side of the same discipline for inbound calls sits in webhook security and signature verification.
Two-way flows need one more rule: when both sides change the same record, which one wins? Teams that have not answered that before a version migration end up with two systems overwriting each other because of migration-window lag. How to define that conflict rule is covered in two-way data synchronization.
Monitoring: you have to notice the break yourself
Three signals catch the large majority of failures in practice. The first is volume: how many records does this connection normally carry per hour, and how many is it carrying now? The second is shape: has the fill rate of critical fields dropped in the records that do arrive? The third is error rate, which is the easiest to watch and the least informative. The cheapest alarm to set up with the highest return is the volume alarm, and it is the one most teams never build.
The most valuable form of a volume alarm is the zero alarm: tell me if nothing arrived during a window when something should have. Quiet hours have to be accounted for — no forms between two and five in the morning is normal. Quota tightening shows up the same way, because once a limit is hit requests are refused and the record flow flattens out. How to manage those limits is covered in API rate limits and quota management.
Cutover day: parallel running and rollback
Framing the migration as a single moment when someone flips a switch creates avoidable risk. A shadow period is healthier: the new version runs in parallel with the old for a week, its output recorded on the side while production is still fed by the old one. Over that week the difference list builds itself, and most surprises become visible without ever touching production.
The rollback plan should be written down too, and it needs two things: how to return to the old version, and who makes that call. When the decision-maker is unclear, rollback is always late. On timing, two blunt rules earn their keep: do not cut over on a Friday, and do not cut over during month-end close. Handing the middle layer to an integration platform can absorb version differences, though it also hides them; we weigh that trade-off in integration platforms.
When is not upgrading the right call?
The standard advice is to stay on the latest version at all times. It has a limit. The first weeks of a new major version are in practice the provider's extended test period, and the team that migrates then discovers the provider's bugs in its own production and waits for fixes. Deprecation windows are usually measured in months. Planning the move for somewhere near the middle of the window, rather than its first week, avoids both early-adopter exposure and last-day panic.
There is also the case where not upgrading at all is right. Migrating a low-impact connection that runs a handful of times a year can cost more effort than simply doing the same work by hand after the shutdown date. The business-impact line in your inventory exists precisely to make that call possible. Deciding to retire a connection deliberately is very different from forgetting it and noticing one day that it stopped; the difference between the two is one sentence of documentation. The wider landscape of connection options sits in our guide to CRM integrations.
Where to start
Three things can be done this week, and none require code. Put every connection in a single table, assign a role as owner to each, and change the technical contact on every provider account to a durable group address. Those three steps catch a meaningful share of silent failures before they happen, because most breakage comes not from a technical gap but from nobody reading the notice.
Next comes monitoring: set a volume alarm on your two most critical connections. Then put a thirty-minute review on the calendar once a quarter — open the inventory, read the providers' change logs, flag credentials approaching expiry. Run that ritual for a year and most breakage stops being an incident and becomes scheduled work.
Keeping connections, triggers and records in one system also shrinks the blast radius of a version change: seeing what is wired to what is half the inventory already done. Rocketly holds workflow automation, form connections and record history in the same place — open a free account and set up your own integration routine.