API Versioning Strategy Block
Document API version management approaches including deprecation policies and migration support.
Overview
The API Versioning Strategy block documents how API versions are managed in your system. It captures the versioning approach, deprecation policies, migration support, and practical examples. Use this block to communicate versioning decisions to API consumers and development teams.
URL Path Versioning
The most common approach, with the version number in the URL path.
Header-Based Versioning
Version specified via HTTP header, keeping URLs clean.
Block Properties
| Property | Required | Description |
|---|---|---|
| strategyName | Yes | Human-readable name for the strategy |
| strategy | Yes | One of 'url-path', 'header', 'query-param', or 'content-negotiation' |
| currentVersion | No | The current/latest version identifier |
| deprecationPolicy | No | How and when versions are deprecated |
| migrationSupport | No | Resources available to help clients migrate |
| sunsetPeriod | No | Time between deprecation announcement and removal |
| examples | No | Array of example API calls showing the versioning pattern |
| notes | No | Additional context and rationale |