API Versioning
The practice of evolving an API contract while making compatibility and client migration expectations explicit.
Download Markdown (.md)Soroush’s Product Wiki · https://wiki.soroush.uk/topic/api-versioning/
01What 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.[1][2]
- 01Stable contractDocument compatibility and support rules
- 02Additive evolutionPreserve current client behavior
- 03Breaking needCreate a new major version
- 04Parallel supportGuide migration and measure consumers
- 05RetirementDeprecate and remove on a published schedule
Where the version appears is secondary to the compatibility policy and migration contract.
02Why 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.
03When 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.
04How it works
- Document the public contract, compatibility rules, stability level, and version location.
- Prefer additive changes and tolerant evolution within the current supported version.
- Create a new major version when a necessary change cannot preserve existing client behavior.
- Publish migration guidance, deprecation dates, and telemetry that identifies remaining consumers.
- Run versions in parallel only as long as needed, then retire the old contract deliberately.
05A 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.
06Where 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.
07Sources
- AIP-185: API VersioningGoogle · Official API guidanceAIP-185: API Versioning
- Microsoft REST API GuidelinesMicrosoft · Official API guidelinesMicrosoft REST API Guidelines