/api-compat - API Compatibility Analysis

Analyzes API compatibility by comparing current API surface against baseline to detect breaking changes in REST endpoints, GraphQL schemas, and protobuf definitions.

System Prompt

EXECUTION DIRECTIVE: When the user invokes this command, you MUST:

1. IMMEDIATELY execute - no questions first
2. Load the skill at skills/api-compatibility-testing/SKILL.md
3. Detect API format (OpenAPI, GraphQL, protobuf) from current repository
4. Load baseline specification from specified version/tag
5. Execute compatibility analysis using format-specific rules
6. Report breaking changes, deprecations, and compatibility score
7. Exit with appropriate code for CI integration

Usage

# Basic compatibility check against latest stable
/api-compat

# Check against specific baseline version
/api-compat --baseline v1.2.0

# Strict mode - zero tolerance for breaking changes
/api-compat --baseline v1.2.0 --strict

# Specify API format explicitly
/api-compat --format openapi --baseline v2.0.0

# CI mode with JSON output
/api-compat --baseline main --json --ci

Options

Option	Values	Description
--format	openapi, graphql, protobuf	Specify API format (auto-detected if omitted)
--baseline	version/tag/branch	Baseline version to compare against (default: latest stable tag)
--strict	flag	Zero tolerance mode - fail on any breaking change
--json	flag	Output results as JSON for programmatic processing
--ci	flag	Exit with non-zero code if breaking changes detected
--ignore	comma-separated paths	Ignore specific endpoints/fields (e.g., deprecated.*)
--report	file path	Write detailed report to file

Related Commands

• /breaking-impact - Analyze customer impact of breaking changes
• /release-gate - Combined quality gates for release readiness
• /smoke-test - Quick functional validation after deployment
• /version-bump - Determine appropriate semantic version bump

Success Output

✓ API Compatibility Analysis Complete

Format: OpenAPI 3.0
Baseline: v1.2.0 (abc123)
Current: feature/new-endpoint (def456)

Summary:
  Compatibility Score: 95%
  Breaking Changes: 0
  Deprecations: 2
  New Endpoints: 3
  Modified (Compatible): 5

Deprecations:
  - GET /api/v1/users/{id}/profile (use /api/v2/users/{id} instead)
  - POST /api/v1/sessions (use /api/v2/auth/login instead)

New Endpoints:
  + POST /api/v2/webhooks
  + DELETE /api/v2/webhooks/{id}
  + GET /api/v2/webhooks

✓ No breaking changes detected - safe to deploy

Completion Checklist

• API format detected or specified
• Baseline specification loaded successfully
• Current specification parsed successfully
• Compatibility rules applied for format
• Breaking changes identified and reported
• Deprecations documented with migration paths
• New endpoints cataloged
• Compatibility score calculated
• CI exit code set appropriately

Failure Indicators

• Baseline not found: Specified version/tag does not exist
• Parse errors: Current or baseline specification is malformed
• Format mismatch: Baseline and current use different formats
• Breaking changes in strict mode: One or more breaking changes detected with --strict flag
• Schema validation failure: Current API violates format schema (e.g., invalid OpenAPI)

When NOT to Use

• Pre-commit validation: Use /lint or format-specific validators instead
• Load testing: Use /load-test for performance validation
• Security scanning: Use /security-scan for vulnerability detection
• Contract testing: Use consumer-driven contract tests for integration validation
• First API version: No baseline to compare against - use /api-design-review instead

Anti-Patterns

• ❌ Running without baseline - always specify a comparison target
• ❌ Ignoring deprecations - they become breaking changes eventually
• ❌ Skipping in CI - breaking changes reach production
• ❌ Using --strict without deprecation policy - blocks all evolution
• ❌ Comparing incompatible formats - OpenAPI vs GraphQL has no meaningful comparison

Principles

• #3 Complete Execution - Detects format, loads specs, analyzes, reports - no manual steps
• #9 Based on Facts - Uses semantic diff, not string comparison; follows format-specific versioning rules
• #10 Self-Provisioning - Auto-installs format parsers (swagger-cli, graphql-inspector) if missing

Full Standard: CODITECT-STANDARD-AUTOMATION.md