api-compatibility-analyzer
npx machina-cli add skill a5c-ai/babysitter/api-compatibility-analyzer --openclawFiles (1)
SKILL.md
2.5 KB
API Compatibility Analyzer Skill
Analyzes API changes between versions to detect breaking changes, assess consumer impact, and suggest migration strategies.
Purpose
Enable API versioning management for:
- Breaking change detection
- Deprecation analysis
- Version comparison
- Consumer impact assessment
- Migration path suggestion
Capabilities
1. Breaking Change Detection
- Detect removed endpoints
- Identify removed fields
- Find type changes
- Flag required field additions
2. Deprecation Analysis
- Track deprecated endpoints
- Monitor deprecation timelines
- Identify usage of deprecated APIs
- Plan sunset schedules
3. Version Comparison
- Compare OpenAPI specs
- Generate detailed diffs
- Categorize changes
- Document migrations
4. Consumer Impact Assessment
- Map affected consumers
- Estimate migration effort
- Identify high-impact changes
- Prioritize notifications
5. Migration Path Suggestion
- Recommend upgrade steps
- Suggest compatibility layers
- Propose versioning strategies
- Design adapter patterns
6. Compatibility Layer Design
- Design facade endpoints
- Plan response translation
- Handle version negotiation
- Implement fallbacks
Tool Integrations
| Tool | Purpose | Integration Method |
|---|---|---|
| OpenAPI-diff | Spec comparison | CLI |
| Optic | API change detection | CLI |
| Akita | Traffic-based detection | API |
| swagger-diff | Swagger comparison | CLI |
| Spectral | API linting | CLI |
Output Schema
{
"analysisId": "string",
"timestamp": "ISO8601",
"versions": {
"base": "string",
"target": "string"
},
"changes": {
"breaking": [
{
"type": "string",
"path": "string",
"description": "string",
"migration": "string"
}
],
"nonBreaking": [],
"deprecations": []
},
"impact": {
"consumers": [],
"severity": "string",
"migrationEffort": "string"
},
"recommendations": []
}
Integration with Migration Processes
- api-modernization: Compatibility verification
- framework-upgrade: API impact analysis
Related Skills
api-inventory-scanner: Endpoint discoveryopenapi-generator: Spec generation
Related Agents
api-modernization-architect: Versioning strategy
Source
git clone https://github.com/a5c-ai/babysitter/blob/main/plugins/babysitter/skills/babysit/process/specializations/code-migration-modernization/skills/api-compatibility-analyzer/SKILL.mdView on GitHub Overview
Analyzes API changes between versions to detect breaking changes, assess consumer impact, and suggest migration strategies. It supports version management, deprecation tracking, and migration planning to minimize consumer disruption.
How This Skill Works
The skill compares API specifications (OpenAPI/Swagger) using tools like OpenAPI-diff, Optic, and swagger-diff to generate detailed diffs. It categorizes changes into breaking, non-breaking, and deprecations, maps affected consumers, estimates migration effort, and proposes upgrade steps and compatibility layers.
When to Use It
- Planning a major version release and validating that breaking changes are intentional and well-documented
- Auditing a refactor to understand consumer impact and necessary migrations
- Tracking deprecations and scheduling sunset timelines with clear migration paths
- Assessing API changes before communicating with downstream consumers
- Designing compatibility layers or adapters to minimize disruption during upgrades
Quick Start
- Step 1: Prepare base and target OpenAPI/Swagger specs for the API you’re migrating
- Step 2: Run the analysis with the preferred diff tools (OpenAPI-diff, Optic, swagger-diff) to produce breaking/non-breaking/deprecation signals
- Step 3: Review findings, prioritize migrations, and document upgrade steps or compatibility layers
Best Practices
- Run baseline vs target comparisons with authoritative OpenAPI specs to catch removed endpoints and required field additions
- Prioritize changes by consumer impact and clearly document migration steps for each change
- Leverage deprecation timelines and sunset plans to align with product roadmap
- Pair diffs with migration recommendations (upgrades, compatibility layers, or versioning strategies)
- Maintain a living catalog of compatibility layer designs and adapter patterns for reuse
Example Use Cases
- Detecting a removed endpoint in v2 and planning a temporary compatibility facade for v1 clients
- Identifying required field additions that would break existing clients and proposing API versioning and migrations
- Mapping deprecated endpoints to sunset schedules and notifying affected teams
- Comparing OpenAPI specs to generate diffs and categorized migrations for a framework upgrade
- Designing adapter patterns to translate responses between old and new API shapes during migration
Frequently Asked Questions
Add this skill to your agents
