# What is API Versioning?

Also called Version Negotiation.

API versioning is the practice of labeling an interface so that changes can be introduced without breaking existing clients. The version may appear in the URL path, in a request header, or in a dated release identifier. Its purpose is to let a provider evolve while callers written against an older contract keep working unchanged.

Three placements dominate. A path segment such as a leading version marker is the most visible and the easiest to route, though it changes every URL when the version changes. A header keeps URLs stable and permits per request selection. A dated version pinned per account, where each caller records the release it was built against, is common among providers that ship frequently.

The distinction that matters is between additive and breaking change. Adding an optional field, a new endpoint, or a new enumerated value is generally safe if clients ignore unknown data. Removing a field, renaming one, tightening validation, or changing a default alters the contract and requires a new version or a long deprecation period.

Supporting many versions is expensive. Every branch multiplies test surface, complicates the data layer, and slows future work, so mature providers limit how many remain live and publish a supported window. Some avoid parallel implementations entirely by translating older requests and responses at the edge into a single internal representation.

Versioning is not a substitute for communication. Clients need a changelog, a migration guide, advance notice, and ideally usage telemetry showing who is still on the old version. Silent behavioral drift within a fixed version is worse than an honest version increment, because callers have no signal that anything changed.

## Key points

- Version in the path, a header, or a dated per-account pin
- Additive changes are safe; removals and renames are not
- Each live version multiplies maintenance and test cost
- Publish a supported window and a migration guide
- Silent behavior drift is worse than a version bump

## In practice

A provider pins each account to the API release that was current when the account was created and sends that date in a header on every response. New accounts get the latest behavior immediately. An existing integration keeps its original response shapes until the team is ready, then overrides the header per request to test the newer version in staging before pinning the account forward.

## Related terms

- [API](/en/glossary/api)
- [REST API](/en/glossary/rest-api)
- [Deprecation Policy](/en/glossary/deprecation-policy)
- [OpenAPI Specification](/en/glossary/openapi-specification)
- [SDK](/en/glossary/sdk)

[Back to the AI Glossary](/en/glossary)