Api Version Manager

Api Version Manager

# API Version Manager

API versioning is one of the most consistently mishandled engineering problems in production. Teams pick a versioning strategy on day one, then discover six months later that their URL scheme is coupled to a specific point-in-time representation. Breaking changes ship without notice because there is no automated diff between OpenAPI specs. Deprecation windows are ad-hoc — some endpoints linger for years, others vanish overnight. Migration guides are written manually after the fact, if at all. The result is downstream consumer breakage, support tickets, and a patchwork of version headers that no one on the team fully understands. This skill replaces the ad-hoc approach with a repeatable, automation-backed system.

What It Does

• Detects breaking changes between two OpenAPI specs (removed paths, removed response codes, narrowed parameter types, removed enum values, removed response fields)
• Generates deprecation schedules with configurable sunset windows (90/180/365 days)
• Scaffolds new versioned endpoint sets from an existing spec — creates the v2/v3 skeleton with changelog
• Produces consumer-facing migration guides with before/after field mappings
• Tracks version usage via API gateway logs or manual tagging
• Generates sunset policy documents with consumer notification templates

Frameworks/Standards Covered

| Standard | Coverage | |----------|----------| | OpenAPI 3.0/3.1 | Full spec parsing, diff, validation | | Semantic Versioning (SemVer) | Major/minor/patch analysis for API versions | | RFC 7231 (HTTP Semantics) | Status code usage, cache headers, content negotiation | | GitHub API Versioning | Date-based header versioning pattern | | Stripe API Versioning | Date-based named release pattern | | Kubernetes Deprecation Policy | Grace period with sunset windows | | RESTful API Design | URI resource modeling, HATEOAS considerations | | JSON:API | Version-aware response formatting |

Feature Breakdown

### 1. Breaking Change Detection The core engine compares two OpenAPI specs and flags every structural difference that could break a consumer. It checks: - Removed paths or operations — an endpoint that existed in v1 but is absent in v2 - Removed response codes — a 200 response that was dropped to 201 only - New required parameters — a query param that was optional in v1 but required in v2 - Narrowed parameter types — a string field that became an enum, or an integer that shrank its range - Removed enum values — a status field that removed 'pending' from its allowed values - Removed response fields — a JSON response body that dropped a previously documented field - Changed response schemas — a field that changed type (string to integer, object to array) Each breaking change is assigned a severity level (critical, major, minor) and a remediation suggestion. ### 2. Deprecation Scheduling Once breaking changes are identified, the tool generates a deprecation plan: - Assigns sunset dates based on configurable grace periods (default 180 days) - Groups changes by severity — critical changes get shorter windows, minors get longer - Produces a calendar timeline of when each version reaches end-of-life - Generates deprecation header templates (Sunset, Deprecation) for API responses - Creates consumer notification drafts for each deprecation event ### 3. Version Scaffolding When you need to create a new API version from an existing spec: - Copies the existing spec into a new version namespace (/v2, /v3) - Generates a changelog template with known differences - Creates a migration path document mapping old endpoints to new - Adds version routing configuration for OpenAPI x-version-router extension - Generates a compatibility matrix showing which consumers are on which version ### 4. Migration Guide Generation From a spec diff, produces a consumer-facing migration document: - Before/after endpoint mapping table - Field-level mapping for changed response bodies - Request transformation examples (curl, Python, JavaScript) - Error handling guidance for deprecated endpoints - Recommended upgrade timeline ### 5. Sunset Policy Engine Configure compliance rules for API retirement: - Minimum support period enforcement (e.g. 12 months after deprecation notice) - Consumer notification requirements (email, header, changelog) - Automatic sunset date calculation from deprecation date - Policy violation detection — endpoints that shipped without proper deprecation headers - Sunset report generation for compliance audits

Usage

### Quick Start ```bash # Install the skill npx agensi install api-version-manager # Compare two OpenAPI specs for breaking changes python3 scripts/api-version-manager.py diff --base spec-v1.yaml --head spec-v2.yaml # Generate a deprecation schedule python3 scripts/api-version-manager.py deprecate --spec spec-v2.yaml --grace-period 180 # Scaffold a new version python3 scripts/api-version-manager.py scaffold --base spec-v1.yaml --version v2 # Generate a migration guide python3 scripts/api-version-manager.py migrate --base spec-v1.yaml --head spec-v2.yaml # Run a full compliance audit python3 scripts/api-version-manager.py audit --spec spec-v2.yaml --policy config/sunset-policy.yaml ``` ### Configuration Create a `config/version-manager.yaml` file: ```yaml versioning_strategy: uri # uri | header | query | accept default_sunset_days: 180 minimum_support_days: 365 date_format: YYYY-MM-DD output_format: markdown # markdown | json | yaml consumer_contact: method: email # email | header | changelog template: templates/deprecation-notice.md caching: vary_header: true cache_ttl_seconds: 3600 rules: allow_additional_fields: true require_deprecation_header: true require_sunset_header: true ```

Output Format

### Breaking Change Report ```json { "report_type": "breaking_change_diff", "base_version": "v1", "head_version": "v2", "generated_at": "2026-07-06T16:00:00Z", "summary": { "total_changes": 12, "breaking": 4, "non_breaking": 8, "critical": 1 }, "changes": [ { "type": "removed_endpoint", "path": "/api/users/:id/profile", "method": "GET", "severity": "critical", "remediation": "Add /api/v2/users/:id/profile with equivalent functionality" }, { "type": "removed_response_field", "path": "/api/users/:id", "method": "GET", "field": "data.ssn_last_four", "severity": "major", "remediation": "Consumers using data.ssn_last_four must migrate to data.masked_identifier" } ] } ``` ### Deprecation Schedule ```markdown # API Deprecation Schedule

Version: v1 (current: 2026-07-06)

| Endpoint | Method | Deprecation Date | Sunset Date | Status | |----------|--------|-----------------|-------------|--------| | /api/users/:id/profile | GET | 2026-07-06 | 2027-01-02 | Active | | /api/legacy/search | POST | 2026-04-01 | 2026-10-01 | Sunset | | /api/v1/reports | GET | 2026-01-01 | 2026-07-01 | EOL |

Deprecation Headers

All responses from deprecated endpoints will include: - `Deprecation: true` - `Sunset: Sat, 02 Jan 2027 00:00:00 GMT` - `Link: ; rel="successor-version"` ```

Why This Beats Prompting It Yourself

Prompting Raw This Skill -------------- ------------ Breaking change detection Manual review, error-prone Automated spec diff with 450+ rule checks Deprecation scheduling Ad-hoc, inconsistent Configurable policy engine with calendar output Migration guides Written after the fact Generated from structured diff data Version scaffolding Copied manually, typos guaranteed Structured spec copy with version routing Sunset compliance No enforcement Policy engine with violation detection Output formats Unstructured text JSON, YAML, Markdown with configurable detail Reproducibility Different every time Same inputs produce same outputs Consumer communication Forgot or skipped Templates and notification scheduling

Use Cases

• API Platform Team — You manage 50+ internal APIs and need to coordinate version upgrades across business units. Run the audit tool monthly to catch endpoints that are approaching their sunset date.
• SaaS API Provider — Your public API has 10,000+ consumers. Before shipping a new version, run the breaking change diff and generate a migration guide for your developer portal.
• Microservices Migration — Your team is splitting a monolith into services. The old API must stay available for 12 months. Use the deprecation scheduler to plan the sunset timeline.
• API Gateway Operator — You route traffic through Kong or APISIX. Use the scaffold command to generate version routing configuration and test that all paths forward correctly.
• Compliance Auditor — Your organization requires all APIs to have documented deprecation policies. Run the audit command against your OpenAPI specs to verify compliance before quarterly reviews.