API Contract Drift Detection

Integration cycles break when API contracts drift silently from their documentation or previous versions. This skill automates the detection of breaking changes, structural mismatches, and behavioral shifts between baseline contracts and current implementations. It moves beyond simple text diffing to perform deep semantic and structural analysis of OpenAPI, GraphQL, and JSON schemas.

What it does

• Breaking change detection identifies modifications in requests or responses that will cause existing consumers to fail.
• Structural normalization resolves references and ignores non-functional changes like property ordering or whitespace to reduce noise.
• Behavioral drift analysis flags changes in data units, defaults, or pagination logic that schema validators often miss.
• Implementation verification compares live runtime responses against declared specifications to find undocumented fields or types.
• Impact scoring assigns severity levels and confidence scores to every detected discrepancy.

How it works

1. Load inputs by providing baseline and current contracts or sharing a schema and a sample runtime response.
2. Normalize and resolve all $ref pointers and inheritance structures to create a comparable flat inventory of endpoints.
3. Execute comparison across methods, parameters, body schemas, status codes, and security requirements.
4. Generate report including a categorized list of findings with specific migration advice and CI/CD gate recommendations.

Frameworks & tools

Supports OpenAPI (Swagger), JSON Schema, GraphQL, and webhook payloads. Compatible with recorded REST responses, gateway definitions, and code-derived schemas.

Why this beats prompting it yourself

Generic prompts often fail to distinguish between additive changes and breaking ones, or they miss subtle drift in nullability and enum constraints. This skill uses a strict classification vocabulary and directional compatibility rules (Request vs. Response) to ensure high-precision audits without false positives from formatting changes.

Use cases

• Pre-deployment gates to determine if a schema change requires a new major version.
• Documentation audits to ensure the codebase actually matches the published Swagger UI.
• Legacy discovery to generate a baseline contract for an undocumented API from recorded traffic.
• Consumer impact analysis to provide specific migration steps for frontend teams when backend contracts change.

Known limitations

Cannot resolve external private $ref URIs without access. Semantic drift detection requires clear naming or documentation context to infer meaning changes.