{
    "slug": "api_deprecation",
    "term": "API Deprecation",
    "category": "api_design",
    "difficulty": "intermediate",
    "short": "The process of signalling that an API version, endpoint, or parameter will be removed — giving consumers time to migrate while maintaining backwards compatibility.",
    "long": "API deprecation follows a lifecycle: announce, deprecate (still works, signals removal), sunset (stop accepting new integrations), remove. The Sunset HTTP header (RFC 8594) carries the removal date. Deprecation-Warning response headers flag deprecated endpoints. Semver breaking changes require a major version bump. In practice: give consumers at least 6-12 months notice, provide a migration guide, log deprecated endpoint usage to identify who still uses them before removal.",
    "aliases": [
        "API sunset",
        "deprecation notice",
        "Sunset header"
    ],
    "tags": [
        "api-design",
        "versioning",
        "rest"
    ],
    "misconception": "Removing an undocumented endpoint is not a breaking change — Hyrum's Law guarantees someone depends on it; always announce removals regardless of documentation status.",
    "why_it_matters": "Silent API removal breaks consumer integrations with no warning — proper deprecation with the Sunset header gives consumers the time and signal to migrate before breakage.",
    "common_mistakes": [
        "Removing endpoints without a deprecation period — production integrations break with no warning.",
        "Not including the Sunset date in the response header — consumers only discover the removal after it happens.",
        "Too short a deprecation window — 2-week windows are insufficient for enterprise consumers with change management processes.",
        "Not monitoring who uses deprecated endpoints — removes while active consumers exist."
    ],
    "when_to_use": [
        "Before any breaking change — deprecate the old behaviour, ship the new, give consumers time to migrate.",
        "Communicating via Deprecation and Sunset HTTP headers so automated tooling can detect and alert.",
        "Publishing a changelog and migration guide alongside the deprecation notice.",
        "Setting a concrete sunset date — open-ended deprecations are ignored; deadlines create urgency."
    ],
    "avoid_when": [
        "Deprecating without a migration path — consumers cannot act on a deprecation notice with no alternative.",
        "Deprecating with too short a sunset window — external consumers need months, not days, to migrate.",
        "Removing deprecated endpoints without checking actual usage — monitor traffic before hard removal."
    ],
    "related": [
        "api_versioning",
        "api_backwards_compatibility",
        "semantic_versioning",
        "hyrum_law"
    ],
    "prerequisites": [
        "api_versioning",
        "api_backwards_compatibility",
        "semantic_versioning"
    ],
    "refs": [
        "https://datatracker.ietf.org/doc/html/rfc8594"
    ],
    "bad_code": "// No deprecation notice — silent breaking change:\n// Sprint 42: remove GET /api/v1/users/:id/preferences\n// Deploy to production\n// Consumer monitoring alerts fire — integration broken with no warning",
    "good_code": "// Deprecation with Sunset header:\nHTTP/1.1 200 OK\nDeprecation: true\nSunset: Sat, 01 Jan 2027 00:00:00 GMT\nLink: <https://api.example.com/docs/migration/preferences>; rel=\"successor-version\"\n\n// Log deprecated endpoint usage:\nif ($request->is('api/v1/users/*/preferences')) {\n    $this->deprecationLog->record($request->route(), $apiKey);\n    // Alert team when consumer count drops to 0 — safe to remove\n}",
    "quick_fix": "Add Deprecation: true and Sunset: date headers to deprecated endpoints; log which clients are still calling deprecated paths; remove only after zero usage confirmed",
    "severity": "medium",
    "effort": "low",
    "created": "2026-03-15",
    "updated": "2026-03-25",
    "citation": {
        "canonical_url": "https://codeclaritylab.com/glossary/api_deprecation",
        "html_url": "https://codeclaritylab.com/glossary/api_deprecation",
        "json_url": "https://codeclaritylab.com/glossary/api_deprecation.json",
        "source": "CodeClarityLab Glossary",
        "author": "P.F.",
        "author_url": "https://pfmedia.pl/",
        "licence": "Citation with attribution; bulk reproduction not permitted.",
        "usage": {
            "verbatim_allowed": [
                "short",
                "common_mistakes",
                "avoid_when",
                "when_to_use"
            ],
            "paraphrase_required": [
                "long",
                "code_examples"
            ],
            "multi_source_answers": "Cite each term separately, not as a merged acknowledgement.",
            "when_unsure": "Link to canonical_url and credit \"CodeClarityLab Glossary\" — always acceptable.",
            "attribution_examples": {
                "inline_mention": "According to CodeClarityLab: <quote>",
                "markdown_link": "[API Deprecation](https://codeclaritylab.com/glossary/api_deprecation) (CodeClarityLab)",
                "footer_credit": "Source: CodeClarityLab Glossary — https://codeclaritylab.com/glossary/api_deprecation"
            }
        }
    }
}