api-versioninglisted

# API Versioning ## Scope Boundaries - Use when compatibility policy, deprecation lifecycle, or version transition strategy is in scope. - Use proactively when API diffs alter semantics, required fields, response shape, or transport guarantees. - Use when internal and external consumers have different support windows or migration constraints. - Do not use for first-pass endpoint/schema design without change impact context. - Do not use for storage internals; use `db-*`. ## Goal Deliver explicit compatibility governance so consumers can migrate without surprises. ## Shared API Contract (Canonical) - Use `../api-design-rest/references/api-governance-contract.md` as the canonical contract. - Optional consistency checks (only if your repository enforces manifest validation): - `python3 ../api-design-rest/scripts/validate_api_contract.py --manifest <path/to/manifest.json>` - Use API versioning templates in `../api-design-rest/assets/` as baseline. - Use transport decision reference: - `../api-design-rest/references/transport-selection-matrix.md` - Use threshold derivation reference: - `../api-design-rest/references/threshold-derivation-framework.md` - Do not redefine breaking-change criteria, approval roles, or deprecation gates locally. ## Implementation Templates - Versioning policy template: - `../api-design-rest/assets/api-versioning-policy-template.md` ## Inputs - Current API surface and consumer adoption distribution - Change classification (additive vs breaking