home / skills / a5c-ai / babysitter / api-compatibility-analyzer

api-compatibility-analyzer skill

safe

/plugins/babysitter/skills/babysit/process/specializations/code-migration-modernization/skills/api-compatibility-analyzer

This skill analyzes API changes across versions to detect breaking changes, assess consumer impact, and guide migration strategies.

npx playbooks add skill a5c-ai/babysitter --skill api-compatibility-analyzer

Review the files below or copy the command above to add this skill to your agents.

Files (2)

SKILL.md

2.5 KB

---
name: api-compatibility-analyzer
description: Analyze API changes for backward compatibility with breaking change detection and consumer impact assessment
allowed-tools: ["Bash", "Read", "Write", "Grep", "Glob", "Edit"]
---

# 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

```json
{
  "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 discovery
- `openapi-generator`: Spec generation

## Related Agents

- `api-modernization-architect`: Versioning strategy

Overview

This skill analyzes API changes across versions to detect breaking changes, assess consumer impact, and recommend migration strategies. It focuses on OpenAPI/Swagger comparisons, deprecation tracking, and producing actionable migration plans. The outputs are structured reports that map changes to affected consumers and suggest compatibility layers or adapters.

How this skill works

The analyzer ingests base and target API specifications (OpenAPI/Swagger) and runs diff and linting tools to classify changes as breaking, non-breaking, or deprecations. It correlates changes with runtime traffic or consumer inventories to estimate impact and migration effort. Finally, it generates structured recommendations and migration steps, including facade or translation patterns when appropriate.

When to use it

Before publishing a new API major or minor version to validate backward compatibility.
During framework or platform upgrades that may alter API behavior or schemas.
When planning sunsetting or deprecation timelines for legacy endpoints.
To prioritize notification and remediation work for downstream consumers.
As part of CI/CD pipelines to block or warn on detected breaking changes.

Best practices

Compare authoritative OpenAPI specs for base and target versions to ensure accurate diffs.
Integrate traffic or consumer inventory data to prioritize high-impact changes.
Classify changes clearly as breaking, non-breaking, or deprecated and attach migration recommendations.
Automate checks in pull requests and release pipelines to catch regressions early.
Provide compatibility layers or adapter patterns for high-risk breaking changes when immediate consumer updates aren’t feasible.

Example use cases

Detecting added required fields and recommending optional fallback handling or staged rollout.
Identifying removed endpoints and mapping affected clients to generate targeted migration tickets.
Comparing two OpenAPI specs to produce a categorized change log for release notes.
Designing a facade endpoint that translates legacy request/response formats to the new API.
Assessing consumer impact to decide whether to postpone a breaking change or provide a compatibility shim.

FAQ

What file formats does the analyzer accept?

Primarily OpenAPI (YAML/JSON) and Swagger specs. You can also feed in generated diffs from CLI tools.

Can it estimate migration effort for downstream services?

Yes. It correlates change severity with consumer usage data to produce a relative migration effort rating and prioritize work.