Api Migration Assistant

Api Migration Assistant

# API Migration Assistant

API migrations are one of the highest-risk operations in software engineering. A single breaking change shipped without detection can cascade through dozens of downstream services, causing integration failures, data corruption, and pager-duty incidents. The challenges are well understood but poorly tooled: - Breaking changes hide in plain sight -- renaming a field, changing a response type, or adding a required parameter can pass CI but break production consumers - Dependency graphs are opaque -- knowing which services consume which endpoints requires manual spelunking through codebases and API docs - Rollback plans are afterthoughts -- most teams plan the migration but not the rollback, turning a bad deploy into a hours-long incident - Protocol migrations are manual -- SOAP to REST, REST to GraphQL, or gRPC to REST each require distinct analysis patterns, and no single tool handles all of them - Consumer communication is reactive -- teams find out about breaking changes when their CI fails, not before The API Migration Assistant solves all of this. It is a single CLI tool that inventories your API surface, identifies breaking changes between versions, maps consumer dependencies, generates migration plans with rollback steps, and produces audit-ready reports.

What It Does

• Analyzes OpenAPI/Swagger specs to detect breaking changes between API versions
• Maps field-level diffs: added, removed, renamed, or type-changed fields across endpoints
• Detects changed HTTP methods, URL path changes, status code changes, and parameter shifts
• Generates structured migration plans with phased rollout steps and rollback instructions
• Produces dependency maps showing which endpoints changed and what consumers may be affected
• Supports REST-to-REST version migrations and protocol-transition assessments (SOAP-to-REST notes)

Frameworks/Standards Covered

| Standard/Framework | Application | |---|---| | OpenAPI 3.0/3.1 | Primary spec format for API definition analysis | | Semantic Versioning (SemVer 2.0) | Breaking change classification (major/minor/patch) | | RESTful API Design Best Practices | Endpoint structure, HTTP method semantics, status codes | | GraphQL Schema SDL | Field-level schema diffing (when comparing REST-to-GraphQL) | | gRPC Proto Buffers | Service definition comparison (protocol migration assessment) | | HTTP Sunset/Deprecation Headers (RFC 8594) | Deprecation planning and consumer communication | | OWASP API Security Top 10 | Security-related change detection (auth/authorization shifts) |

Features

### Breaking Change Detection Engine The assistant parses two OpenAPI specs (current and target) and performs a deep structural comparison: ``` Endpoint-level: path additions, removals, HTTP method changes, URL restructuring Parameter-level: added/removed required params, type changes, default value shifts Response-level: status code changes, response schema modifications, new error codes Field-level: added fields, removed fields, type changes, format changes, nullable changes Auth-level: authentication scheme changes, scope/permission modifications ``` Each change is classified as either BREAKING or NON-BREAKING with an explanation of why. ### Migration Plan Generator From the diff output, the assistant generates a phased migration plan: - Phase 0: Preparation -- deprecation announcements, consumer notification, documentation updates - Phase 1: Additive -- deploy new endpoints alongside existing ones (parallel run capability) - Phase 2: Deprecation -- mark old endpoints as deprecated with Sunset headers - Phase 3: Cutover -- switch consumers to new endpoints, monitor for errors - Phase 4: Cleanup -- remove old endpoints, archive documentation, update specs Each phase includes specific actions, success criteria, and rollback steps. ### Rollback Planning Every migration plan includes an automatic rollback section: - What signals indicate a rollback is needed (error rate spikes, latency increases, consumer complaints) - Exact steps to restore the previous API version - Data integrity verification after rollback - Estimated rollback time based on deployment infrastructure ### Compliance Validation The assistant validates migration plans against configurable rules: - `max_breaking_changes` -- fail the plan if more than N breaking changes exist - `min_deprecation_days` -- require endpoints to be deprecated for N days before removal - `require_rollback_plan` -- enforce that every phase has a rollback step - `require_deprecation_headers` -- check that deprecated endpoints set proper HTTP headers ### CI Integration Mode The JSON output format is designed for CI pipeline consumption: ```json { "plan_id": "mig-20260706-abc123", "status": "needs_review", "breaking_changes": 3, "non_breaking_changes": 12, "endpoints_affected": ["/api/users", "/api/orders"], "max_breaking_violation": false, "rollback_ready": true, "estimated_rollback_minutes": 8 } ```

Usage

### Quick Start ```bash # Analyze differences between two API specs python scripts/cli.py diff --current spec-v1.yaml --target spec-v2.yaml # Generate a full migration plan python scripts/cli.py plan --current spec-v1.yaml --target spec-v2.yaml # Validate a migration plan against safety rules python scripts/cli.py validate --plan migration-plan.json --config config/config.yaml # Generate a Markdown report from a diff or plan python scripts/cli.py report --input diff-output.json --format markdown ``` ### Configuration Create a config file at `config/config.yaml`: ```yaml migration: strict_mode: true max_breaking_changes: 5 min_deprecation_days: 90 require_rollback_plan: true require_deprecation_headers: true output: default_format: markdown include_diffs: true include_recommendations: true json_pretty: true security: check_auth_scheme_changes: true check_permission_scope_changes: true check_sensitive_data_exposure: true ``` ### CLI Reference | Command | Description | |---|---| | `diff` | Compare two API specs and list all changes | | `plan` | Generate a full migration plan from spec diff | | `validate` | Validate a migration plan against rules | | `report` | Generate a formatted report from any output | | `inventory` | List all endpoints and operations in a spec | | `check` | Single-spec static analysis for potential issues | | `export` | Export migration plan to different formats |

Output Format

The assistant produces structured Markdown reports like this example: ``` # API Migration Report: spec-v1.yaml -> spec-v2.yaml

Summary

- Current Version: 1.0.0 - Target Version: 2.0.0 - Breaking Changes: 3 - Non-Breaking Changes: 12 - Endpoints Scanned: 24

Breaking Changes

### PUT /api/users/{id} -> PATCH /api/users/{id} Type: HTTP Method Change Impact: CONSUMERS MUST UPDATE their HTTP method Migration: Update client from PUT to PATCH, adjust idempotency handling ### POST /api/orders (removed) Type: Endpoint Removal Impact: ALL CONSUMERS affected, replacement at POST /api/v2/orders Migration: Update endpoint URL and request body format ### GET /api/products: response.items[].price (type change) Type: Field Type Change (string -> number) Impact: CONSUMERS parsing price as string will break Migration: Update parsers, existing numeric strings are valid JSON numbers

Migration Plan

Phase 0: Preparation (Days 1-90) - Announce v2 deprecation with 90-day sunset - Publish migration guide with code examples - Set Deprecation and Sunset headers on all v1 endpoints Phase 1: Additive (Days 1-90) - Deploy v2 endpoints alongside v1 - Monitor for errors and latency changes - Provide opt-in migration path for early adopters ...

Rollback Plan

Signal: Error rate >1% or latency >500ms p99 on v2 endpoints Steps: 1. Route traffic back to v1 endpoints 2. Verify v1 endpoints serving correct responses 3. Confirm consumer error rates return to baseline Estimated Time: 5 minutes (DNS/lb propagation)

Recommendations

- Add deprecation headers to all v1 endpoints before cutover - Consider staggered consumer migration with canary testing - Update all SDK/client libraries before v1 removal ```

Why This Beats Prompting It Yourself

AspectAd-Hoc PromptingThis Skill Raw Prompting API Migration Assistant --- --- --- Spec Parsing Manual reading, error-prone Automated diff engine with field-level granularity Breaking Change Detection Subjective, depends on reviewer Algorithmic with classification rules Migration Plan Generic advice, no structure Phased plan with timelines, actions, and rollback Rollback Planning Usually forgotten Automatic rollback section per phase CI Integration Impossible JSON output for pipeline consumption Consistency Varies by prompt and reviewer Reproducible rules-based analysis Compliance Checks None Configurable validation against safety rules Audit Trail None Versioned migration plans with timestamps

Use Cases

• API version bump (v1 to v2) -- Team plans a major version release and needs a complete diff of all breaking changes with a migration schedule
• Protocol migration planning -- Engineering lead evaluating SOAP-to-REST migration needs a structured assessment of what changes and what stays
• CI/CD pre-deploy gate -- DevOps engineer integrates the assistant into CI pipeline to block deploys that introduce unplanned breaking changes
• API consolidation -- Company merging two API surfaces into one unified spec needs a dependency map and migration plan for all consumers
• Regulatory compliance audit -- Compliance officer needs documentation of API changes between versions for SOC 2 or HIPAA audit trail