migrating-apis_skill

Overview

This skill automates API migrations between versions, platforms, or frameworks with minimal downtime. It guides specification analysis, scaffolds code, implements handlers and middleware, and generates OpenAPI documentation. The goal is a predictable, testable migration path that preserves contracts and reduces production risk.

How this skill works

The skill inspects existing API specifications and resource models, then generates scaffolding for routes, controllers, models, and middleware. It applies validation, authentication hooks, database integrations, and produces OpenAPI 3.0 output. Migration steps include generating boilerplate, implementing business logic, adding tests, and preparing deployment patterns (blue/green or canary).

When to use it

• Upgrading API major or minor versions while keeping client compatibility
• Porting an API between frameworks (e.g., Flask → FastAPI, Express → Fastify)
• Moving an API across platforms or languages (e.g., monolith → microservices)
• Refactoring endpoints or data models that break existing contracts
• Standardizing documentation and generating OpenAPI specs for clients

Best practices

• Start from a documented API contract and run contract/contract-testing first
• Use versioning, feature flags, and blue/green or canary deployments to minimize downtime
• Automate generation of scaffolding and tests to reduce human error
• Keep backward-compatible response shapes where possible and provide clear deprecation paths
• Run integration and end-to-end tests against staging with production-like data and monitoring

Example use cases

• Migrate REST v1 endpoints to a v2 schema while routing v1 traffic to legacy handlers
• Port a Python Flask API to FastAPI to gain async performance and auto-generated docs
• Convert monolithic endpoints into microservice routes with centralized auth middleware
• Upgrade authentication flow (API key → OAuth2) and update client onboarding docs
• Generate OpenAPI 3.0 spec from legacy code and scaffold new endpoints with validation