# API Versioning

The practice of evolving an API contract while making compatibility and client migration expectations explicit.

- Type: practice
- Domain: Engineering & architecture
- Level: Intermediate
- Last reviewed: 2026-09-24
- Original: [Soroush’s Product Wiki](<https://wiki.soroush.uk/topic/api-versioning/>)

## What it means

API versioning is the policy and mechanism used to distinguish incompatible generations of an interface. A version may appear in a path, header, media type, schema, or protocol package, but the essential concern is contract compatibility: additive changes often fit an existing version, while breaking changes require coordination or a new major version.

## Why it matters

APIs connect software released on different schedules. A clear version policy lets providers improve a product without unexpectedly breaking mobile apps, partners, or internal services, and makes the cost and timing of migrations visible to product teams.

## When to use it

Define a versioning policy before an API has independently deployed consumers. Introduce a new version for genuinely incompatible contract changes, not every feature. An internal interface with coordinated releases may instead use compatibility tests and a short migration window.

## How it works

1. Document the public contract, compatibility rules, stability level, and version location.
2. Prefer additive changes and tolerant evolution within the current supported version.
3. Create a new major version when a necessary change cannot preserve existing client behavior.
4. Publish migration guidance, deprecation dates, and telemetry that identifies remaining consumers.
5. Run versions in parallel only as long as needed, then retire the old contract deliberately.

## A practical example

A payments API must replace a single address string with structured fields. The provider adds the new structure to v1 first, measures adoption, and reserves v2 for removing the old field. Partner dashboards show migration status before v1 retirement.

## Where it breaks

Version labels do not make changes safe by themselves. Supporting several versions multiplies testing, documentation, security, and operational work. Over-versioning fragments users, while indefinite support prevents teams from retiring costly behavior.

## Common mistakes

- Creating a new version for every additive field or implementation change.
- Calling a change backward compatible without testing real client behavior.
- Announcing deprecation without usage telemetry, migration help, or a credible timeline.
- Embedding version logic inconsistently across endpoints and documentation.

## Visualization

[View the visualization on the website](<https://wiki.soroush.uk/topic/api-versioning/#visualization-api-versioning>)

## Sources

1. [AIP-185: API Versioning](<https://google.aip.dev/185>) — Google · Official API guidance
2. [Microsoft REST API Guidelines](<https://github.com/microsoft/api-guidelines/blob/vNext/azure/Guidelines.md>) — Microsoft · Official API guidelines

## Related topics

- [Application Programming Interface \(API\)](<https://wiki.soroush.uk/topic/application-programming-interface/>)
- [API-First Design](<https://wiki.soroush.uk/topic/api-first-design/>)
- [Endpoint](<https://wiki.soroush.uk/topic/endpoint/>)
