api-versioning
Installation
SKILL.md
API Versioning
Use this skill when
- Choosing a versioning strategy (URI, header, content)
- Deprecating old versions
- Migrating consumers
Do not use this skill when
- Private internal-only endpoints
- Greenfield pre-release APIs
Instructions
- Prefer additive and backward-compatible changes first.
- Choose versioning: URI for visibility, header/accept for precision, never query param.
- Version breaking changes explicitly and document them.
- Deprecate with warnings (headers, docs) and a sunset date.
- Keep older versions alive long enough for consumers to migrate.
- Support unknown fields tolerance to soften evolution.
- Track which versions are in production use.