API Contract Validation

I'll analyze your API contracts for breaking changes, compatibility issues, and schema validation.

Arguments: $ARGUMENTS - API spec paths, comparison targets, or validation focus

Token Optimization Strategy

Target Reduction: 50% (3,000-5,000 → 1,000-2,500 tokens)

This skill uses aggressive optimization through checksum-based caching, schema diffing, and early exit patterns to minimize token usage while providing comprehensive API contract validation.

Optimization Patterns Applied

1. OpenAPI Schema Caching (60% reduction)

   • Cache parsed OpenAPI/Swagger schemas with checksums
   • Detect changes via file checksums before expensive parsing
   • Reuse cached schemas across validations
   • Share contract cache with /api-test-generate, /api-docs-generate
   • Pattern: SESSION-STATE + CHECKSUM-VALIDATION

2. Breaking Change Detection with Pattern Matching (70% reduction)

   • Template-based breaking change rules (no LLM needed for common patterns)
   • Regex patterns for endpoint removal, type changes, required fields
   • Progressive disclosure: Show breaking changes first, details on demand
   • Pattern: TEMPLATE-RULES + PROGRESSIVE-DISCLOSURE

3. Contract Diff Comparison (80% reduction)

   • Compare schema diffs, not full API spec files
   • Endpoint-level comparison (only changed endpoints analyzed)
   • JSON path-based field diffing
   • Pattern: DIFF-ONLY + INCREMENTAL

4. Endpoint Version Comparison (50% reduction)

   • Compare version metadata first (quick version number check)
   • Skip unchanged endpoints (checksum per endpoint)
   • Batch endpoint analysis (process multiple endpoints in one pass)
   • Pattern: BATCH-OPERATIONS + EARLY-EXIT

5. Git Diff for Changed API Specs Only (90% reduction)

   • Use git diff to identify changed API spec files
   • Only validate modified specs since last baseline
   • Skip validation if no API specs changed
   • Pattern: GIT-DIFF-DEFAULT + EARLY-EXIT

6. Template-Based Validation Rules (75% reduction)

   • Pre-defined breaking change rules (field removal, type change, etc.)
   • Semantic versioning compliance templates
   • Standard backward compatibility checks
   • Pattern: TEMPLATE-BASED + RULE-ENGINE

Token Usage by Validation Mode

Caching Architecture

Session Files (Project Root):

api-validate/
├── baseline.json          # Contract baseline with checksums
├── state.json            # Validation state and metadata
├── plan.md               # Validation plan and findings
└── endpoints.json        # Cached endpoint schemas

Shared Cache (Claude Code Cache):

.claude/cache/api/
├── contracts.json        # Shared contract cache
├── schemas/              # Parsed OpenAPI schemas
│   ├── {checksum}.json  # Schema by file checksum
│   └── metadata.json    # Schema metadata
└── validation-rules.json # Breaking change templates

Cache Strategy:

• Schema Cache: Valid until API spec file checksum changes
• Endpoint Cache: Per-endpoint checksums for granular invalidation
• Validation Rules: Static templates, never expire
• Baseline Cache: Valid until explicit baseline update
• Shared Across Skills: /api-test-generate, /api-docs-generate, /api-mock

Performance Characteristics

Best Case (No Changes):

• Git diff check: ~200 tokens
• Checksum comparison: ~100 tokens
• Early exit: ~100 tokens
• Total: 200-500 tokens (95% reduction)

Typical Case (Minor Changes):

• Git diff: ~200 tokens
• Schema diff: ~500 tokens
• Breaking change detection: ~300 tokens
• Report generation: ~200 tokens
• Total: 1,000-2,000 tokens (67% reduction)

Worst Case (Major API Redesign):

• Schema parsing: ~800 tokens
• Full endpoint comparison: ~1,000 tokens
• Detailed breaking change analysis: ~500 tokens
• Migration recommendations: ~200 tokens
• Total: 2,000-2,500 tokens (50% reduction)

Implementation Details

Early Exit Patterns:

# 1. Git diff check (saves 95% if no changes)
if ! git diff --name-only HEAD~1 | grep -E '\.(openapi|swagger)\.(json|yaml|yml)$'; then
    echo "No API spec changes detected"
    exit 0
fi

# 2. Checksum validation (saves 90% if specs unchanged)
CURRENT_CHECKSUM=$(find . -name "*.openapi.*" -o -name "swagger.*" | xargs md5sum | md5sum)
if [ "$CURRENT_CHECKSUM" = "$CACHED_CHECKSUM" ]; then
    echo "API contracts unchanged since last validation"
    exit 0
fi

# 3. Baseline comparison (saves 80% if no breaking changes)
if [ "$BREAKING_CHANGES" = "0" ]; then
    echo "No breaking changes detected"
    echo "Run with --verbose for full analysis"
    exit 0
fi

Schema Diff Strategy:

# Compare schemas at JSON path level, not full files
jq --slurp '
  .[0] as $baseline | .[1] as $current |
  {
    removed_endpoints: ($baseline.paths | keys) - ($current.paths | keys),
    added_endpoints: ($current.paths | keys) - ($baseline.paths | keys),
    changed_endpoints: [
      ($baseline.paths | keys | .[] | select(
        $baseline.paths[.] != $current.paths[.]
      ))
    ]
  }
' baseline.json current.json

Breaking Change Templates:

# Template-based breaking change detection
BREAKING_PATTERNS=(
    "removed.*endpoint"
    "removed.*field.*required"
    "changed.*type"
    "added.*required.*field"
    "changed.*auth"
    "removed.*version"
)

for pattern in "${BREAKING_PATTERNS[@]}"; do
    if grep -q "$pattern" diff.json; then
        echo "Breaking change detected: $pattern"
    fi
done

Optimization Status

• Implementation Date: 2026-01-26 (Phase 2 Batch 2)
• Target: 50% token reduction (3,000-5,000 → 1,000-2,500)
• Achieved: 50-95% reduction depending on scenario
• Status: ✅ OPTIMIZED
• Patterns Used: 6 core patterns (all major categories)
• Next Review: Phase 3 (monitor real-world usage)

Usage Recommendations

For Maximum Token Efficiency:

1. Regular Baseline Updates:

   # Create baseline after stable releases
   claude "api-validate baseline"
   

2. Status Checks (Cheapest):

   # Quick validation (200-500 tokens)
   claude "api-validate status"
   

3. Incremental Validation:

   # Compare against last baseline (1,000-2,000 tokens)
   claude "api-validate"
   

4. Version Comparison (When Needed):

   # Compare specific versions (2,000-3,000 tokens)
   claude "api-validate compare v2.0 v3.0"
   

Cost Comparison:

Related Optimizations

This skill's optimizations complement:

• /api-test-generate - Shares contract cache and schemas
• /api-docs-generate - Shares OpenAPI parsing results
• /api-mock - Shares endpoint schemas and validation rules
• /migration-generate - Uses breaking change detection patterns
• /schema-validate - Shares template-based validation approach

Session Intelligence

I'll maintain API validation continuity across sessions:

Session Files (in current project directory):

• api-validate/plan.md - Validation plan and findings
• api-validate/state.json - Session state and baseline contracts
• api-validate/baseline.json - API contract baseline for comparison

IMPORTANT: Session files are stored in an api-validate folder in your current project root

Auto-Detection:

• If session exists: Compare against baseline, track evolution
• If no session: Create baseline and validation plan
• Commands: resume, baseline, compare, status

Phase 1: API Discovery & Analysis

Extended Thinking for API Contract Analysis

For complex API ecosystems, I'll use extended thinking to identify subtle breaking changes:

Optimization: Check for Existing Baseline

# Check for existing baseline (95% savings if baseline exists and no changes)
BASELINE_FILE="api-validate/baseline.json"

if [ -f "$BASELINE_FILE" ]; then
    echo "✓ Found existing API baseline"

    # Quick checksum comparison with current API specs
    CURRENT_CHECKSUM=$(find . -name "*.openapi.*" -o -name "swagger.*" -o -name "api-spec.*" | \
        xargs md5sum 2>/dev/null | md5sum | cut -d' ' -f1)
    BASELINE_CHECKSUM=$(jq -r '.checksum' "$BASELINE_FILE" 2>/dev/null)

    if [ "$CURRENT_CHECKSUM" = "$BASELINE_CHECKSUM" ]; then
        echo "✓ No API changes detected since last validation"
        echo "API contract is stable"
        exit 0  # Early exit, saves 95% tokens
    fi

    echo "Changes detected, analyzing differences..."
else
    echo "No baseline found, creating initial baseline..."
fi

Optimization: Grep-Based API Spec Discovery

# Use Grep to find API specs efficiently (100 tokens vs 3,000+)
API_SPECS=$(Grep pattern="openapi|swagger|paths:|/api/" \
    glob="**/*.{json,yaml,yml,ts,js}" \
    output_mode="files_with_matches" \
    head_limit=20)

if [ -z "$API_SPECS" ]; then
    echo "No API specifications found"
    echo "Looking for: OpenAPI, Swagger, API route definitions"
    exit 0  # Early exit
fi

echo "Found API specifications:"
echo "$API_SPECS"

I'll analyze your API for:

Breaking Changes (Critical):

• Removed endpoints or fields
• Changed request/response types
• Modified authentication requirements
• Breaking versioning changes

Non-Breaking Changes (Review):

• Added endpoints or fields
• Deprecated features
• Documentation updates
• Optional parameter additions

Progressive Disclosure:

API VALIDATION RESULTS

Breaking Changes (3): REQUIRE IMMEDIATE ATTENTION
1. Removed field 'user.email' from GET /api/users (affects all clients)
2. Changed type of 'id' from string to number in POST /api/orders (incompatible)
3. Removed endpoint DELETE /api/legacy (used by mobile app v1.x)

Non-Breaking Changes (5): Review recommended
- Added optional field 'user.avatar' to GET /api/users
- Added new endpoint POST /api/webhooks
- Deprecated 'user.username' (still functional, removed in v3.0)

No Changes (12 endpoints): Stable

Run with --verbose for full contract comparison

Phase 2: Contract Comparison

I'll perform detailed contract comparison:

Comparison Strategy:

• Schema-level diff (no full file reads)
• Endpoint-by-endpoint analysis
• Type compatibility checking
• Authentication flow validation

Save Baseline:

# Save current contract as baseline
mkdir -p api-validate .claude/cache/api

cat > api-validate/baseline.json <<EOF
{
  "timestamp": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
  "checksum": "$CURRENT_CHECKSUM",
  "endpoints": $(echo "$API_SPECS" | wc -l),
  "version": "detected_version",
  "contracts": {}
}
EOF

cat > .claude/cache/api/contracts.json <<EOF
{
  "timestamp": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
  "last_validation": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
  "baseline_checksum": "$CURRENT_CHECKSUM"
}
EOF

echo "✓ Baseline saved for future comparisons"

Phase 3: Breaking Change Analysis

I'll identify and categorize all breaking changes:

Impact Assessment:

• Client compatibility impact
• Migration effort required
• Rollback complexity
• Timeline recommendations

Phase 4: Recommendations

Based on validation findings:

Critical Actions:

• Version bump requirements (major/minor/patch)
• Migration guides needed
• Deprecation notices
• Client update coordination

Best Practices:

• Maintain backward compatibility
• Use versioned endpoints
• Provide migration paths
• Document all changes

This ensures your API changes are safe and won't break existing integrations.