Agent skill · software engineering · secondsky
api-versioning-strategy
Implements API versioning using URL paths, headers, or query parameters with backward compatibility and deprecation strategies. Use when managing multiple API versions, planning breaking changes, or designing migration paths.
Why this skill is useful
Provides specific implementation patterns and code examples for API versioning that the AI wouldn't reliably generate on its own.
What it needs
About 1k tokens when loaded. Last updated 2026-08-06. 204 stars on the source repository.
What this skill does
API Versioning Strategy Choose and implement API versioning approaches with proper deprecation timelines. Versioning Methods Method Example Pros Cons -------- --------- ------ ------ URL Path /api/v1/users Clear, cache-friendly URL clutter Header API-Version: 1 Clean URLs Hidden, harder to test Query ?version=1 Easy to use Not RESTful URL Path Versioning (Recommended) Version Adapter Pattern Deprecation Headers Safe vs Breaking Changes Safe Changes (no version bump): Adding optional fields Adding new endpoints Adding optional parameters Breaking Changes (requires new version): Removing fields Changing field types Restructuring responses Removing endpoints Deprecation Timeline Phase Duration Actions ------- ---------- --------- Deprecated 3 months Add headers, docs Sunset Announced 3 months Email users Read-Only 1 month Disable writes Shutdown - Return 410 Gone Best Practices Support N-1 versions minimum Provide 6+ months migration window Include migration guides with code examples Monitor version usage to inform deprecation
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills secondsky/api-versioning-strategy