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:

   bash

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

2. •

   Status Checks (Cheapest):

   bash

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

3. •

   Incremental Validation:

   bash

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

4. •

   Version Comparison (When Needed):

   bash

   # 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.