API integration for modern businesses

An integration that has run without attention for two years stops returning the right data. Nothing was deployed on your side. Nobody changed a configuration. The vendor shipped a release, classified it as backwards compatible, and by their own published definition they were correct. Your integration still broke.

The business impact is rarely the failure itself, which is usually fixed in a day once someone identifies it. It is that the work is unplanned, arrives without warning, and lands on whoever is available rather than whoever built it. Multiply that across a dozen connected systems and you have a standing tax on engineering capacity that never appeared in any project budget, because every one of those integrations was scoped as a piece of work that finished.

That framing is the useful correction. An API integration is not a feature you ship once. It is a permanent dependency on another company's product decisions, and it needs to be scoped, budgeted and monitored on that basis.

What an integration actually commits you to

When an integration is approved, the cost presented is the build. The costs that follow are real, recurring, and predictable enough that they can be planned for rather than absorbed as surprises.

• The vendor will change the API. Some changes will be announced, and some will be considered too minor to announce.
• The credentials will expire, be rotated, or belong to someone who leaves.
• The volume will grow until an assumption made during the build stops holding.
• A library the integration depends on will reach end of life and need replacing.
• At some point the vendor will retire the version you built against entirely.

None of these are failures of engineering. They are the normal lifecycle of a dependency on somebody else's product. The distinction that matters commercially is between a business that has budgeted for this and one that treats every occurrence as an emergency.

Read the deprecation policy before you write the code

Most integration projects begin with the API reference. The more consequential document is the versioning and deprecation policy, because that is where the vendor states how much notice you will get and what they consider themselves free to change without any.

What mature vendors commit to

The commitments are usually specific and worth reading before selecting a platform. Microsoft states that it declares a Microsoft Graph version deprecated at least 24 months in advance of retiring it, and applies the same 24-month notice to individual APIs that have reached general availability. That is a concrete planning horizon: it tells you that a rewrite forced by Microsoft will never arrive with less than two years of warning, and it also tells you that ignoring a deprecation notice for eighteen months is a decision rather than an oversight.

Stripe takes a different approach to the same problem. It separates releases into major releases, which contain changes that are not backwards compatible, and monthly releases, which contain only backwards-compatible changes. Requests are pinned to a version, either by the account default or by the version the installed SDK was built against, and webhook events use the version set when the endpoint was created. The practical effect is that a Stripe integration does not break because Stripe shipped something; it breaks when somebody upgrades a version deliberately.

Both models are defensible and they impose different obligations on you. A pinned-version model means you carry the responsibility for scheduling upgrades, and an integration left alone for years will be running against an increasingly old contract. A notice-period model means the clock starts without you doing anything, and somebody has to be reading the announcements.

The changes vendors classify as safe

This is the part that surprises people, and it is the single most useful thing to understand about maintaining integrations. Vendors publish what they consider backwards compatible, and the list routinely includes changes that will break code written without care.

Microsoft publishes both lists for Microsoft Graph. The comparison is instructive:

Read the left column as a list of things that will happen to your integration without notice. A new enumeration member will arrive and code that switches exhaustively on the old set will fall through. Paging will be introduced on a collection that previously returned everything, and an integration that reads the first response and stops will silently begin processing a fraction of the records. An opaque identifier will get longer and a database column sized to yesterday's length will start truncating or rejecting. Error codes will change and any logic that branches on a specific code or parses an error string will take the wrong path.

None of that is the vendor behaving badly. Their definition of compatibility is a contract about the shape of the interface, not a promise that careless clients will keep working. The obligation is on the integration to be built for it.

Build for the changes that are officially not breaking

The practices that follow from the table above are unglamorous and they are what separates an integration that runs for five years from one that needs attention every quarter.

1. 1

   Ignore fields you do not recognise

   A response containing a property your code has never seen is normal and must not be an error. Deserialise into a structure that tolerates unknown fields rather than one that rejects them, which is the default behaviour in several strict parsers.

2. 2

   Treat every enumeration as open

   Handle the values you know and route anything else to an explicit unknown path that logs and continues. Code that assumes it has seen every possible status will break the first time the vendor adds one.

3. 3

   Always follow pagination, even when there is only one page

   If the API returns a next-page token or link, follow it. An integration that assumes a single response is complete works perfectly until the collection grows or the vendor introduces paging, and then loses data silently.

4. 4

   Branch on status codes and documented error identifiers, never on message text

   Human-readable error messages are presentation, not contract. They get rewritten for clarity and localised, and any logic that matches on their wording breaks when they do.

5. 5

   Do not assume the size or format of identifiers

   Store opaque references as generously sized text. Assuming a fixed length, or that an identifier is numeric because it currently looks numeric, is a common and avoidable failure.

6. 6

   Pin the version explicitly where the platform allows it

   An integration that inherits whatever version happens to be the account default will change behaviour when somebody else changes that setting. Pinning makes upgrades a deliberate, testable act.

Credentials have a lifecycle, and ignoring it is how integrations die

A large share of integration outages have nothing to do with code. A token expired and nothing refreshed it. A password was rotated under a security policy. An integration was authenticated as a named employee, and that employee left, and their account was disabled on their last day exactly as the offboarding process requires.

The business impact is disproportionate because these failures are total and instant rather than gradual. The system does not degrade; it stops. And because the cause sits in an identity system rather than in the integration, the people investigating usually look in the wrong place first.

Choosing the authentication method

The right choice is usually the one that avoids tying the integration to a human identity. A dedicated machine identity survives staff changes, can be scoped narrowly, and produces audit records that clearly separate automated activity from user activity.

Refresh tokens are not a set-and-forget credential

Where OAuth 2.0 is used, the refresh token becomes the long-lived secret and deserves proportionate handling. The IETF Best Current Practice for OAuth 2.0 Security, published as RFC 9700, is the current reference. It states that refresh tokens for public clients must be sender-constrained or use refresh token rotation, and recommends that authorisation and resource servers use mechanisms for sender-constraining access tokens such as mutual TLS or demonstrating proof of possession.

For a business integration the practical translation is short. Store refresh tokens with the same care as a database password, in a secret store rather than in a configuration file or a workflow definition. Expect rotation, which means the token you hold after a refresh may not be the token you started with, and persist the new one immediately. Monitor for refresh failures explicitly, because a refresh that stops working is the most common silent start to an outage.

Least-privilege scoping of the account itself is covered in the CRM integration article and applies identically here.

Choose the integration pattern deliberately

Requirements for integration arrive described as real time almost by default. It is worth testing that, because real time is the most expensive pattern to build, the most expensive to operate, and frequently not what the business actually needs.

The honest question is what decision changes if the data is an hour old. For a support agent looking at a customer record during a call, the answer is that the conversation goes wrong, so the requirement is genuine. For a finance report produced on Monday morning, an overnight batch is not a compromise; it is the correct design, and it is dramatically simpler to reason about and recover.

These combine well. A common and robust arrangement is webhooks for immediacy with a nightly batch reconciliation behind them, so that anything the event stream missed is corrected within a day without anyone noticing. That pairing gives the responsiveness the business asked for and the recoverability the business assumed it was getting.

You cannot maintain what you have not written down

Ask most growing businesses to list every external system their software talks to and the list will be incomplete. Integrations are added by different people at different times, some through code and some through automation platforms configured by non-engineers, and no single person holds the whole picture. The consequence appears when a credential must be rotated, a vendor announces a retirement, or a security review asks where customer data goes.

The OWASP API Security Top 10 treats this as a named risk, API9, Improper Inventory Management. Its prevention guidance is direct: inventory all API hosts and document important aspects of each one of them including environment, network access scope and version, inventory integrated services and document their role in the system and what data is exchanged, and document all aspects of your API such as authentication, errors, redirects and rate limiting.

For a business rather than an API provider, that reduces to a register that fits on one page per integration and answers seven questions.

• Which two systems does it connect, and in which direction does data move?
• What data crosses the boundary, and does any of it constitute personal data?
• Which credential does it use, where is that credential stored, and when does it expire?
• Which API version is it built against, and what has the vendor said about retiring it?
• Where does it run, and who is alerted when it fails?
• Who owns it, by name, and who is the fallback?
• What breaks in the business if it stops for a day?

The last question is the one that determines how much of the rest matters. An integration whose failure is noticed within an hour and costs nothing needs far less operational care than one whose failure silently corrupts a month of financial reporting.

Find out about vendor changes before your users do

Every mature API provider publishes a changelog and a developer announcement channel, and almost nobody subscribes to them. Assigning that reading to a named person, with the register above as the list of what to care about, converts an unpredictable class of incident into scheduled maintenance.

Where the vendor offers a sandbox, a small suite of tests that exercises the calls the integration actually makes, run on a schedule against that sandbox, will surface behavioural change earlier than production will. The value is not thorough coverage. It is that the tests assert the assumptions the integration depends on: that this field is present, that this collection is not paged, that this identifier fits. Those are precisely the assumptions the vendor considers itself free to change.

Detecting the failures that occur without any vendor change — the integration that is running but processing nothing — is a monitoring problem rather than a testing one, and is covered in the CRM integration article.

Building the integration layer, or buying it

There are three defensible answers and the right one depends on how many integrations exist and how unusual their logic is.

A vendor's own native connector should be the default when one exists and does what is required. It is maintained by somebody whose job is to keep it working when their own API changes, which is the single most valuable property an integration can have. Rejecting a native connector because it does ninety per cent of the requirement, in favour of building the whole thing to capture the last ten, is a decision that should be made explicitly rather than by reflex.

A workflow automation platform such as n8n sits in the middle and covers a wide range of real requirements: orchestration between systems, scheduled synchronisation, transformation, and routing. Its main advantage is reversibility. Changing a workflow is cheaper than redeploying an application, which matters most in the period when the process is still settling. Its main risk is that logic accumulates in a place that is not version controlled or reviewed unless someone insists that it is.

Custom code earns its place when the transformation is genuinely complex, when the integration is part of a product rather than an internal process, or when data volumes make a general-purpose tool uneconomic. It offers the most control and it carries the entire maintenance burden described in this article. That is an acceptable trade when the integration is central to how the business operates and a poor one when it is moving records between two systems on a schedule.

A representative scenario

A composite of situations we see repeatedly; no client detail is included.

A company runs an integration that pulls records from a supplier platform each night into its own database. It works for eighteen months. Then the nightly totals begin to look low, not dramatically, and it is attributed to a quiet trading period. Six weeks later somebody reconciles properly and finds that roughly eighty per cent of records are missing.

The supplier had introduced pagination on the endpoint as the dataset grew. Under their published policy this was a backwards-compatible change and was not individually announced. The integration read the first response and stopped, exactly as it had always done, and there had never been more than one page before. No error was raised at any point, because nothing had gone wrong from the perspective of either system.

The fix took under a day: follow the pagination links, and add a check comparing the record count against the previous run that alerts on a variance beyond a threshold. The six weeks of decisions made on incomplete data could not be undone, and reconstructing what had been affected took considerably longer than the fix.

Frequently asked questions

Conclusion

The integrations that survive are not the cleverest ones. They are the ones written by someone who read the vendor's deprecation policy, assumed the response would change shape, avoided tying the credential to a person, chose batch where batch was sufficient, and wrote down that the integration exists so that somebody could find it later.

None of that is expensive at the point of building. All of it is expensive to retrofit after an integration has silently returned incomplete data for six weeks.