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?
| Approach | Example |
|---|---|
| URL path | /api/v2/employees |
| Header | API-Version: 2026-01-01 |
| Date-based | Stripe-style dated versions |
| Additive only | New 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.