api-versioning-strategy

name	api-versioning-strategy
enabled	true
description	Use when performing api versioning strategy — template for defining and implementing API versioning strategies. Covers versioning scheme selection, backward compatibility analysis, migration path design, client communication planning, and deprecation timelines to manage API evolution without breaking existing consumers.
required_connections	[{"prefix":"github","label":"GitHub"}]
config_fields	[{"key":"api_name","label":"API Name","required":true,"placeholder":"e.g., Orders API"},{"key":"current_version","label":"Current Version","required":true,"placeholder":"e.g., v2"},{"key":"new_version","label":"New Version","required":true,"placeholder":"e.g., v3"}]
features	["DEVOPS","API_MANAGEMENT"]

API Versioning Strategy Skill

Define versioning strategy for {{ api_name }} migration from {{ current_version }} to {{ new_version }}.

Workflow

Phase 1 — Current API Analysis

API INVENTORY
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
[ ] API name: {{ api_name }}
[ ] Current version: {{ current_version }}
[ ] Endpoints in current version: ___
[ ] Active consumers:
    - Internal services: ___
    - External partners: ___
    - Public clients: ___
[ ] Request volume (daily): ___
[ ] SLA commitments: ___

Phase 2 — Versioning Scheme

VERSIONING APPROACH
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Select versioning method:
[ ] URL path versioning: /{{ new_version }}/resource
[ ] Header versioning: Accept: application/vnd.api.{{ new_version }}+json
[ ] Query parameter: ?version={{ new_version }}
[ ] Content negotiation

DECISION MATRIX
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Factor              | URL Path | Header  | Query Param
Discoverability     | HIGH     | LOW     | MEDIUM
Cache-friendliness  | HIGH     | LOW     | HIGH
Client simplicity   | HIGH     | MEDIUM  | HIGH
RESTful purity      | LOW      | HIGH    | LOW
Current approach    | [ ]      | [ ]     | [ ]

Selected approach: ___
Justification: ___

Phase 3 — Breaking Changes Analysis

BREAKING CHANGES
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
[ ] Document all changes from {{ current_version }} to {{ new_version }}:

Endpoint changes:
- Added: ___
- Modified: ___
- Removed: ___

Schema changes:
- Fields added: ___
- Fields renamed: ___
- Fields removed: ___
- Type changes: ___

Behavior changes:
- Pagination: ___
- Error format: ___
- Authentication: ___
- Rate limits: ___

Backward-compatible changes (no version bump needed):
- ___

Phase 4 — Migration Path

CLIENT MIGRATION PLAN
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
[ ] Migration guide documentation written
[ ] SDK updated for {{ new_version }}
[ ] Code examples provided for each breaking change
[ ] Migration timeline:
    - {{ new_version }} available: ___
    - {{ current_version }} deprecated: ___
    - {{ current_version }} sunset: ___
    - Parallel support window: ___ months
[ ] Client communication:
    [ ] Changelog published
    [ ] Email notification to API consumers
    [ ] Developer portal updated
    [ ] Migration support channel created

Phase 5 — Implementation

IMPLEMENTATION CHECKLIST
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
[ ] {{ new_version }} endpoints implemented
[ ] {{ current_version }} routing still functional
[ ] Version-aware middleware/gateway configured
[ ] API documentation updated (OpenAPI/Swagger)
[ ] Integration tests cover both versions
[ ] Monitoring tracks per-version metrics:
    - Request volume by version
    - Error rates by version
    - Latency by version
[ ] Deprecation headers added to {{ current_version }} responses

Counter-Rationalizations

Shortcut	Counter	Why
"We can skip some steps for this case"	Adapt the workflow steps, don't skip them	Skipped steps are where incidents and oversights originate
"The user seems to already know what to do"	Complete all workflow phases with the user	The workflow catches blind spots that experience alone misses
"This is a minor case, full process is overkill"	Scale the process down, don't turn it off	Minor cases become major when unstructured; the process scales, not disappears
"I'll fill in the details later"	Complete each section before moving on	Deferred details are forgotten; real-time capture is more accurate
"The template output isn't necessary"	Always produce the structured output format	Structured output enables comparison, audit trails, and handoff to other teams

Output Format

Produce an API versioning strategy document with:

1. Version summary (current state, changes, new version)
2. Versioning scheme (selected approach with rationale)
3. Breaking changes catalog (complete list with migration steps)
4. Timeline (availability, deprecation, sunset dates)
5. Client communication plan (channels, schedule, support)