Your customer opens their dashboard, the sync is broken, and you're hearing about it from them before your own monitoring caught it. That's the real cost of reactive connector maintenance, and it compounds fast as your integration catalog grows. Here's what's actually going on when a third-party API changes, and what a more proactive approach looks like.
TLDR:
- Your initial build cost covers only 30-40% of the true cost of an in-house integration over time
- Silent breaking changes like field renames can write
nullto your data for weeks before anyone notices - Pin every connector to an explicit API version and monitor
Deprecationresponse headers in production - An embedded iPaaS makes sense once you're managing 5+ connectors with active versioning cycles
- hotglue handles connector version migrations and can stand up new connectors in one to two weeks from sandbox access
What Is API Versioning and Why It Breaks Integrations
API versioning is how software providers manage change. When a third-party API evolves, the provider assigns a new version so existing integrations have time to adapt before the old one disappears. Think of it as a controlled deprecation schedule, not an immediate swap.
The problem is that "controlled" is relative. A provider might give 90 days notice. Another might give six months. Some give none at all. And if your product has a connector built on top of that API, every version change is a maintenance event waiting to happen.
For a CPO or Head of Partnerships, this matters because your customers feel it first. A sync stops working. A field goes missing. An auth flow returns a 401. The integration your team built six months ago is now outdated, and the fix requires engineering time you did not budget for.
According to Postman's 2024 State of the API Report, the average application runs on between 26 and 50 APIs. That's a lot of upstream surfaces that can change underneath you.
API versioning is a recurring cost that compounds as your user-facing SaaS integrations catalog grows.
Breaking vs. Non-Breaking API Changes
Not all API changes are created equal. When a provider ships an update, the first question to ask is whether your connector actually needs to change at all.
Breaking changes require action. Non-breaking changes generally do not. Here is how to tell them apart:
Breaking changes, act immediately:
- A field is removed from a response, meaning any downstream system reading that field will either error or silently receive nothing.
- A field is renamed (e.g.,
user_nametousername), which looks minor but breaks any mapping that references the old key. - A field's data type changes (e.g., string to integer), which can corrupt data at the point of ingestion.
- An HTTP method changes (e.g., PUT to PATCH), causing requests to fail outright.
- Authentication requirements change, locking your connector out entirely.
- An endpoint is removed, which tends to be the loudest failure of the bunch.
Non-breaking changes, monitor but no rush:
- New optional fields added to responses, which your connector can safely ignore until you decide to use them.
- New optional request parameters or endpoints that expand what the API can do without disrupting existing behavior.
- Bug fixes that correct behavior to match documentation, though worth verifying your connector was not relying on the old behavior.
The real danger is the silent breaking change: a field rename your connector swallows without erroring, writing null downstream for weeks before anyone notices. That is a monitoring problem stacked on top of a versioning problem.
Common API Versioning Strategies
Four patterns show up repeatedly when third-party providers version their APIs. Knowing which one a provider uses tells you a lot about how painful a migration will actually be.
URI Path Versioning
The version lives directly in the URL: /v1/invoices becomes /v2/invoices. QuickBooks Online uses this pattern. It is easy to spot in a changelog and easy to test side by side, but it means updating every hardcoded endpoint in your connector when a new version ships.
Query Parameter Versioning
The version is passed as a parameter: /invoices?version=2024-01. Some providers like Stripe use date-based variants of this. Your base URL stays the same, which sounds convenient, but it can make it harder to catch version drift in code reviews.
Custom Request Header Versioning
The version travels in a request header instead of the URL. The endpoint looks identical across versions, which keeps URLs clean but makes the version invisible unless you inspect the actual request. HubSpot uses header-based versioning for parts of its API.
Media Type Versioning
The version is embedded in the Accept header, like Accept: application/vnd.api+json;version=2. Least common in the tools your customers actually use day-to-day, but worth recognizing when you see it.
The versioning strategy a provider picks shapes how you build and maintain connectors. URI versioning is the most explicit. Header versioning is the easiest to miss, which is a reliable way to find out at 11pm on a Friday.
The Hidden Cost of In-House Connector Maintenance
Building an integration is the easy part. What comes after is where the real cost hides.
The initial engineering estimate usually captures only 30–40% of the true total cost of an in-house integration. The concerns around embedded iPaaS stigma often stem from teams underestimating exactly this hidden cost. The rest gets consumed by error handling, API endpoint changes, schema drift, and connector rebuilds that nobody scoped for.
For an enterprise ERP connector, the two-year cost of ownership routinely exceeds the original build cost. One version migration, one field rename, one auth flow change from QuickBooks or NetSuite, and your team is back in the weeds. Multiply that across a catalog of ten or twenty connectors, and you have a meaningful engineering tax running permanently in the background.
The subtler cost is opportunity cost. Every sprint spent patching a Shopify connector is a sprint not spent on your core product.
How Third-Party Providers Communicate API Changes
Responsible providers follow a rough three-phase model: an announcement when the new version ships, an active deprecation window where the old version still works but signals its retirement through response headers, and a hard sunset date when the old version stops responding. During the deprecation window, well-behaved APIs return a Deprecation header and a Sunset header on every response, giving any monitoring system a machine-readable signal that action is required.
Beyond headers, good providers maintain a public changelog, send direct email notices to registered developers, and publish migration guides before the sunset date. Stripe is a reasonable example here. QuickBooks and Salesforce both publish versioning calendars you can track.
Bad communication looks like a blog post buried in a developer forum, a 30-day notice lost in an email thread, or no notice at all until connectors start failing in production. Legacy accounting APIs are repeat offenders. On-premise systems like QuickBooks Desktop sometimes ship version changes through software updates that your customers install on their own machines, with no API notice reaching you whatsoever.
For any team maintaining connectors across a broad catalog, the practical answer is to monitor changelog RSS feeds, register developer accounts under a shared engineering email, and track Deprecation response headers in your integration layer. Waiting for a customer to report a broken sync is the most expensive way to find out an API changed.
How to Audit Your Integration Catalog for Version Risk
Start with your most customer-critical connectors: accounting, CRM, payroll. If integrating QuickBooks with your SaaS platform breaks, customers notice within hours. Lower-traffic connectors can wait.
Run through each active connector and answer four questions:
- Which API version is the connector pinned to, and is that version still supported?
- Does the provider publish a versioning calendar or changelog you can subscribe to?
- How long has the provider historically given between deprecation announcement and sunset?
- Who on your team owns this connector if it breaks today?
Providers with short deprecation windows (under 60 days) or poor changelog hygiene belong in a high-risk tier. Build a simple table ranking connectors by risk, customer impact, and owner.
| Risk Tier | Criteria | Example Providers |
|---|---|---|
| High | Short deprecation window, no changelog | Legacy accounting APIs, on-premise ERP |
| Medium | Changelog exists, 60-90 day windows | HubSpot, Shopify |
| Low | Published versioning calendar, 6+ months | Stripe, Salesforce |
Any connector without a clear owner is automatically high risk regardless of provider behavior. Ownership gaps are where version changes go undetected longest.
Best Practices for Keeping Connectors Current
Five habits separate teams that catch version changes early from teams that find out through a customer complaint.
- Subscribe to provider changelogs at the engineering team level, beyond a personal inbox. Use a shared alias and route notices into your issue tracker automatically.
- Pin every connector to an explicit API version in your code and connector registry. Never let a connector resolve to "latest" in production.
- Run backward compatibility tests after every provider release. A test suite that hits a staging version of each connector and validates field shapes catches renames and type changes before they reach customers.
- Monitor
DeprecationandSunsetresponse headers in your integration layer. If a header appears in production traffic, it should trigger an alert, not sit silently in a log file. - Set internal migration deadlines well ahead of the provider's sunset date. If Salesforce gives you six months, start the migration in month two.
The underlying principle is that connector maintenance is a product function, not an incident response. When it runs as a background process, version changes become scheduled work. When it runs reactively, they become emergencies.
When to Build Connectors In-House vs. Use an Embedded iPaaS
The build-in-house case is real, but narrow. It makes sense when your integration touches a proprietary internal system with no third-party connector, you have unusual authentication requirements no vendor supports, or you maintain fewer than three connectors with low change frequency.
Outside those conditions, the math changes fast. Each connector you own is a recurring obligation. API version changes, schema drift, auth flow updates, and provider-specific edge cases all land on your engineering backlog indefinitely. Across a catalog of ten or more connectors touching QuickBooks, Salesforce, or Shopify, that obligation becomes a part-time engineering role disguised as maintenance, which is why choosing the best embedded iPaaS solution matters.
An embedded iPaaS platform makes sense when connector count is growing, your providers have active versioning cycles, and your team's time is better spent on your core product.
| Scenario | Build In-House | Use Embedded iPaaS |
|---|---|---|
| Proprietary internal system | Yes | No |
| 1-3 low-change connectors | Yes | Optional |
| 5+ connectors, active versioning | No | Yes |
| No dedicated integrations engineer | No | Yes |
| Customer-facing integration catalog | No | Yes |
How hotglue Approaches Connector Maintenance at Scale
At hotglue, we handle connector maintenance so our customers do not have to. When a third-party API ships a version change, our integrations team monitors it, migrates the connector, and keeps syncs running. Your engineering backlog stays clear.
The open-source connector model is a meaningful part of this. Our Singer and Airbyte-compatible connectors are fully inspectable. Teams can fork, extend, or audit any connector in the catalog instead of trusting a black box to behave correctly after an upstream API change.
The scale matters too. We process roughly 10 billion records weekly across 38,000+ active tenants. At that volume, API change detection is not a manual process. Patterns surface faster, version drift gets caught earlier, and migrations happen before customer syncs start failing.
When a new connector is needed or an existing one requires a version migration, we can stand it up in one to two weeks from sandbox access. That is the turnaround most in-house teams cannot realistically match alongside normal product development.
If your connector catalog is growing and API versioning is becoming a recurring tax on your engineering team, hotglue is the best way to fix it. Compare hotglue to other embedded iPaaS options, or head straight to hotglue.com. Your engineering backlog will thank you.
Final Thoughts on API Versioning and Connector Maintenance at Scale
Keeping connectors current is less about technical difficulty and more about having a system that catches changes before your customers do. The teams that do this well subscribe to changelogs, pin versions explicitly, and treat migrations as planned work with real deadlines. If your team is spending more time patching connectors than building your core product, see how hotglue approaches this.
FAQ
What's the difference between a breaking and non-breaking API change, and how do I know which ones require immediate action?
Breaking changes require immediate engineering response. These include removed fields, renamed fields, data type changes, and authentication requirement changes that will cause your connector to error or silently write corrupted data downstream. Non-breaking changes like new optional fields or additional endpoints can be monitored without urgency, since your existing connector will continue working until you choose to adopt them.
How do I audit my connector catalog for API version risk before something breaks in production?
Start with your highest-impact connectors first: QuickBooks, Salesforce, and Shopify should be your first pass, since a broken sync there gets noticed within hours. For each connector, check which API version it is pinned to, whether the provider publishes a versioning calendar you can subscribe to, and who on your team owns that connector today. Any connector without a named owner is high risk regardless of how stable the provider is.
Should I build connector maintenance in-house or use an embedded iPaaS when my integration catalog hits five or more connectors?
Once you are managing five or more connectors across providers with active versioning cycles (like QuickBooks, Salesforce, or NetSuite), in-house maintenance typically becomes a part-time engineering role that never appears in your headcount plan. An embedded iPaaS like Hotglue handles API version migrations, schema drift, and connector rebuilds as a managed function, so your team is not pulled off product work every time Salesforce ships a new API version.
What does connector maintenance actually cost in-house, and why does the initial build estimate understate it?
The initial build estimate typically covers only 30 to 40% of the true two-year cost of an integration. The rest gets consumed by error handling, API endpoint changes, schema drift, and connector rebuilds that nobody scoped for in the original sprint. For an enterprise ERP connector like NetSuite or Sage 300, a single version migration or auth flow change can easily exceed the original build cost in engineering hours.
How quickly can an embedded iPaaS stand up a new connector when a third-party API ships a version change?
Hotglue's integrations team can stand up a new connector or complete a version migration in one to two weeks from sandbox access, a turnaround that most in-house engineering teams cannot match alongside normal product development. The open-source connector model means you can inspect, fork, or audit any connector in the catalog, so you are never trusting a black box to behave correctly after an upstream API change.