Skip to content
Scope an integration

Glossary

What is API versioning?

API versioning is how an API provider releases changes without breaking existing integrations, by keeping older versions available for a period of time.

API versioning is the practice of labelling an API’s releases, for example in the URL (/v2/), a header or a date, so that breaking changes go into a new version while existing clients keep working on the old one. Providers announce deprecations and eventually retire old versions, which forces integrations to upgrade.

How does it work?

ApproachExample
URL path/api/v2/employees
HeaderAPI-Version: 2026-01-01
Date-basedStripe-style dated versions
Additive onlyNew fields added, nothing removed

For an integration team, versioning is mostly a maintenance problem. Each platform you connect to has its own release calendar and deprecation policy, and an integration that worked at launch can stop working a year later without any change on your side.

Where it shows up in integrations

  • Integration maintenance HRIS, CRM and LMS vendors deprecate endpoints and fields every year.
  • Your own API If customers build on your API, versioning protects them from your changes.
  • Marketplace listings Platform partners may require apps to move to new API versions by a deadline.

Common pitfalls

  • Not tracking deprecation notices from the platforms you integrate with.
  • Parsing responses so strictly that a new field breaks the integration.
  • Removing or renaming fields in your own API without a version change.
  • Leaving no owner for upgrades once the integration is live.