Api Deprecation Handler

Api Deprecation Handler

# API Deprecation Handler

Removing an API endpoint without warning destroys developer trust, breaks production integrations, and floods support with tickets. Most teams have no structured process for deprecation — they either keep dead endpoints running forever or kill them cold turkey with no migration path. API providers like Stripe, GitHub, and OpenAI give 6-12 months notice with Sunset headers (RFC 8594), structured 410 responses, and migration guides. Your API consumers deserve the same treatment. This skill automates the entire deprecation lifecycle so you never break an integration again.

What It Does

• Generates and validates Sunset and Deprecation HTTP headers per RFC 8594
• Scans API codebases for endpoints nearing or past their sunset dates
• Auto-generates migration guides with code examples for replacement endpoints
• Schedules brownout tests — random 410 errors that escalate over time
• Tracks consumer impact — who is still hitting deprecated endpoints
• Produces deprecation timelines with phased enforcement stages

Frameworks/Standards Covered

| Standard / Framework | Support | Details | |---|---|---| | RFC 8594 (Sunset Header) | Full | Generates and validates Sunset, Deprecation, and Link headers | | OpenAPI 3.x | Full | Reads deprecated: true from OpenAPI specs to auto-detect deprecations | | Express.js | Middleware template | deprecationHeaders() middleware for deprecated routes | | FastAPI / Starlette | Middleware template | DeprecationMiddleware class with header injection | | Django / Django REST | Middleware template | DeprecationMiddleware with endpoint registry | | Flask | Decorator template | @deprecated() decorator with sunset date | | Spring Boot (Java) | @Deprecated annotation | Scans @Deprecated annotations and generates reports | | API Gateway (Kong, Zuplo) | Policy templates | Response transformer configs for deprecation headers | | 410 Gone responses | Full | Structured JSON error bodies with migration links |

Detailed Feature Breakdown

### Sunset Header Engine The core engine generates RFC 8594-compliant HTTP headers. Given a deprecation date and a sunset date, it produces: ``` Sunset: Sat, 29 Mar 2027 00:00:00 GMT Deprecation: Sat, 29 Mar 2026 00:00:00 GMT Link: ; rel="deprecation" ``` The engine validates date formats, checks that sunset is after deprecation, and auto-calculates warning periods. For brownout phases, it randomly omits headers to simulate the endpoint disappearing. ### Compliance Scanner The scanner walks your codebase and API routes to find: - Endpoints without deprecation headers that should have them - Endpoints past their sunset date still returning 200 instead of 410 - Missing Link headers with migration URLs - OpenAPI specs with `deprecated: true` but no runtime header implementation - Consumers still calling endpoints past sunset (via access logs) ### Migration Guide Generator When an endpoint is deprecated, consumers need a clear path to the replacement. The migration generator: 1. Reads the OpenAPI spec or route config to find the replacement endpoint 2. Compares request/response schemas between old and new versions 3. Documents breaking changes with before/after code examples 4. Generates a migration guide in Markdown, HTML, or plain text 5. Includes code snippets for Python, JavaScript, cURL, and Go ### Brownout Scheduler Brownout testing gradually introduces failures so consumers migrate before the hard deadline. - Phase 1: 5% of requests return 410 (month 3 of deprecation) - Phase 2: 20% of requests return 410 (month 6) - Phase 3: 50% of requests return 410 (month 9) - Phase 4: 100% of requests return 410 (sunset date, the endpoint is gone) The scheduler respects a configurable consumer allowlist for internal/monitored traffic that should never see brownouts. ### Consumer Impact Tracker Parses access logs to identify which clients (by API key, IP range, or user-agent) are still using deprecated endpoints. Generates a ranked list by request volume so you know who to contact first. Outputs CSV reports for email campaigns.

Usage

### Quick Start ```bash # Initialize a deprecation plan for an API api-deprecation-handler init --api-name "My API" --current-version v2 --sunset-version v1 --deprecation-date "2026-07-01" --sunset-date "2027-07-01" --migration-url "https://docs.example.com/migration" # Scan codebase for deprecation compliance api-deprecation-handler scan --path ./api-routes/ # Generate a migration guide api-deprecation-handler migrate --old-spec ./openapi-v1.yaml --new-spec ./openapi-v2.yaml --output ./docs/migration-guide.md # Check RFC 8594 compliance on live endpoints api-deprecation-handler check --endpoint https://api.example.com/v1/users # Generate consumer impact report api-deprecation-handler impact --access-logs ./logs/access.log --deprecated-endpoints /v1/users,/v1/orders ``` ### Configuration Create a `.deprecation-config.yaml` in your project root: ```yaml api: name: "My Public API" base_url: "https://api.example.com" support_email: "api-support@example.com" deprecations: - endpoint: "/v1/users" method: GET deprecation_date: "2026-07-01" sunset_date: "2027-07-01" replacement: "/v2/users" migration_url: "https://docs.example.com/migration/v1-to-v2" brownout: enabled: true schedule: - start: "2026-10-01" probability: 0.05 - start: "2027-01-01" probability: 0.20 - start: "2027-04-01" probability: 0.50 - endpoint: "/v1/orders" method: POST deprecation_date: "2026-06-01" sunset_date: "2026-12-01" replacement: "/v2/orders" migration_url: "https://docs.example.com/migration/orders-v2" compliance: require_sunset_header: true require_deprecation_header: true require_link_header: true return_410_after_sunset: true warn_if_missing_migration_url: true notifications: email_consumers: true reminder_frequency: "monthly" escalate_after_days: 90 ```

Output Format

### Deprecation Compliance Report ``` API Deprecation Compliance Report Generated: 2026-07-06T11:30:00Z API: My Public API ENDPOINT STATUS SUMMARY ---------------------- Total endpoints scanned: 47 Deprecated endpoints: 8 Compliant: 5 Non-compliant: 3 Past sunset: 1 NON-COMPLIANT ENDPOINTS ---------------------- 1. /v1/users GET Status: MISSING_SUNSET_HEADER Issue: No Sunset header in responses Remediation: Add "Sunset: Wed, 01 Jul 2026 00:00:00 GMT" 2. /v1/inventory POST Status: PAST_SUNSET Issue: Sunset was 2026-03-15, still returning 200 OK Remediation: Return 410 Gone with migration link 3. /v1/reports GET Status: MISSING_LINK_HEADER Issue: No Link header pointing to migration guide Remediation: Add "Link: ; rel="deprecation"" CONSUMER IMPACT -------------- Consumer "partner-acme-corp" made 12,847 requests to /v1/users in the last 30 days. Consumer "internal-dashboard" made 3,201 requests to /v1/users. Consumer "mobile-app-v3" made 891 requests to /v1/orders. BROWNOUT STATUS -------------- /v1/users: Phase 1 active (5% brownout since 2026-10-01) /v1/orders: No brownout scheduled RECOMMENDATIONS -------------- 1. Contact partner-acme-corp about /v1/users deprecation (12K requests/month) 2. Add Link header to /v1/reports responses 3. Return 410 Gone on /v1/inventory immediately (90 days past sunset) ```

Why This Beats Prompting It Yourself

Prompting an LLM This Skill --- --- --- RFC compliance May know about Sunset headers but forgets RFC 8594 specifics Generates spec-compliant headers with validation Codebase scanning Cannot read your actual route definitions Walks filesystem and OpenAPI specs Brownout logic Cannot implement probabilistic failure injection Configurable multi-phase brownout schedules Migration guide generation Generic advice, no schema comparison Compares request/response schemas for breaking changes Consumer impact analysis No access to your access logs Parses real log files for consumer identification Reproducibility Different results every time you ask Deterministic, config-driven output Multi-framework support Knows one framework at a time Ships templates for Express, FastAPI, Django, Flask, Spring Boot, API gateways

Use Cases

• SaaS API Provider — You run a public API with thousands of developers. Version v2 replaces v1 and you need to migrate consumers over 12 months without breaking anyone. The skill generates Sunset headers, brownout schedules, and consumer impact reports.
• Internal Microservices Migration — Your platform team is refactoring the order service. Internal service consumers need 6 months notice. The skill generates deprecation headers on the old endpoints and tracks which services still call them.
• API Gateway Policy Enforcement — You manage APIs through Kong or Zuplo. The skill generates response transformer configs that inject deprecation headers at the gateway level without touching service code.
• OpenAPI-Driven Deprecation — You maintain OpenAPI specs with `deprecated: true` on some endpoints. The skill reads these specs, validates that runtime headers match, and alerts on discrepancies.
• Compliance Auditing — Your API needs to meet RFC 8594 compliance for SOC 2 or ISO 27001. The skill generates compliance reports that auditors can verify.