← Integration Engineering
Integration Engineering

Your Integration Needs Versions Too, Not Only the API

19 Oct 2026·3 min read

You change how a "department" field is mapped and deploy it. The next morning, every customer on that integration sees their reports grouped differently. Nobody asked for it. Providers version their APIs. Your integration code, or the connectors you use, needs versions too.

Three numbers, three meanings

  • Major (1.x.x): a breaking change, like a field renamed or removed.
  • Minor (x.4.x): something new that does not break old use.
  • Patch (x.x.2): a bug fix.

This is semantic versioning. Once a version is released, it must not change. So "we run 1.4.2" means the same thing every day.

Pin production, test on staging

Pinning means production uses an exact version, like 1.4.2, not "whatever is newest". In npm, ~1.2.3 accepts new patch versions, ^1.2.3 accepts new minor and patch versions, and a plain 1.2.3 accepts only itself.

npx --yes semver -r "~1.2.3" 1.2.9 1.3.0 2.0.0
I ran it: it printed only 1.2.9. With "^1.2.3" it printed 1.2.9 and 1.3.0. Needs Node.js installed.

When a new version comes out, point a staging setup at it, run the same requests on both, and compare. Move production’s pin only if the difference is what you expected. Allow automatic updates only where a surprise is fine, usually patch releases.

Do this in 60 secondsOpen the package.json of a project you ship and count the dependencies that start with ^. Each can move to a newer version on a fresh install without a lock file.
Today’s AI angleIf a new version renames a tool or field, an AI agent may not fail loudly. It may pick a different tool. Pin the version your agent was tested with, and test again before you move the pin.
Your Integration Needs Versions Too, Not Only the API · Ali Huzaifa