Sunset- und Deprecation-Header für API-Abschaltung praktisch nutzen

1. Warum stille API-Abschaltung Integrationen zerstört

Externe Entwicklerteams, die eine REST-API integrieren, haben in der Regel keinen direkten Einblick in die interne Roadmap des API-Betreibers und erfahren von einer Abschaltung meist erst, wenn ihre eigene Anwendung mit Fehlern ausfällt. Diese Art der Kommunikation über Produktionsausfälle statt über proaktive Ankündigung beschädigt das Vertrauen in die API nachhaltig und führt oft zu dringenden, ungeplanten Notfall-Migrationen auf Integratorenseite.

Eine kontrollierte Abschaltung braucht deshalb einen Kommunikationskanal, der direkt in den API-Antworten selbst steckt, statt sich auf Changelogs, Mailinglisten oder Blog-Posts zu verlassen, die Integratoren möglicherweise nie lesen. Genau diese Rolle übernehmen die Deprecation- und Sunset-Header.

Anders als ein einmaliger Blog-Post erreicht ein HTTP-Header jeden Client bei jeder tatsächlichen Anfrage, wodurch die Wahrscheinlichkeit deutlich sinkt, dass eine Ankündigung schlicht übersehen wird, weil sie zum falschen Zeitpunkt veröffentlicht wurde oder in einem selten gelesenen Newsletter unterging.

2. Der Deprecation-Header: sofortige Kennzeichnung als veraltet

Der Deprecation-Header signalisiert, dass ein Endpoint als veraltet markiert ist, entweder mit dem Wert true oder mit einem konkreten Datum, ab dem die Kennzeichnung gilt. Clients, die diesen Header auswerten, können frühzeitig Warnungen loggen oder Entwicklerteams benachrichtigen, lange bevor der Endpoint tatsächlich abgeschaltet wird.

Wichtig ist, dass der Deprecation-Header allein noch keine Aussage über den genauen Abschalttermin trifft, sondern nur den Status kommuniziert. Für den konkreten Zeitpunkt der endgültigen Abschaltung ist der separate Sunset-Header zuständig, der beide Header zusammen zu einem vollständigen Kommunikationspaar macht.

In der Praxis empfiehlt es sich, den Deprecation-Header bereits zu setzen, sobald die interne Entscheidung zur Abschaltung feststeht, auch wenn das genaue Sunset-Datum noch nicht final verhandelt ist, damit aufmerksame Integratoren schon frühzeitig mit der Planung ihrer Migration beginnen können.

<?php
declare(strict_types=1);

use Symfony\Component\HttpFoundation\Response;

final class DeprecatedEndpointHeaderSubscriber
{
    private const DEPRECATED_ROUTES = [
        'api_orders_v1_list' => new \DateTimeImmutable('2026-12-31T23:59:59+00:00'),
    ];

    public function onKernelResponse(Response $response, string $routeName): void
    {
        if (!isset(self::DEPRECATED_ROUTES[$routeName])) {
            return;
        }

        $sunset = self::DEPRECATED_ROUTES[$routeName];
        $response->headers->set('Deprecation', 'true');
        $response->headers->set('Sunset', $sunset->format(\DateTimeInterface::RFC7231));
        $response->headers->set(
            'Link',
            '</api/v2/orders>; rel="successor-version"'
        );
    }
}

3. Der Sunset-Header: das konkrete Abschaltdatum

Der Sunset-Header enthält ein konkretes Datum im HTTP-Date-Format, ab dem der Endpoint nicht mehr verfügbar sein wird. Anders als der Deprecation-Header ist der Sunset-Header explizit zukunftsgerichtet und maschinenlesbar auswertbar, sodass automatisierte Monitoring-Systeme bei Integratoren Warnungen auslösen können, sobald das Sunset-Datum in einen konfigurierten Vorlaufzeitraum fällt (etwa 30 Tage vorher).

RFC 8594 spezifiziert explizit, dass der Sunset-Header keine Garantie ist, dass der Endpoint exakt zu diesem Zeitpunkt abgeschaltet wird, sondern eine Absichtserklärung. Ein API-Betreiber sollte den Termin trotzdem verlässlich einhalten, sobald er einmal über diesen Header kommuniziert wurde, um Integratoren nicht durch wiederholte Verschiebungen zu verunsichern.

Ein weiterer praktischer Aspekt ist, dass sich ein einmal kommuniziertes Sunset-Datum nicht ohne Vertrauensschaden vorziehen lässt: Sobald Integratoren ihre Migrationsplanung nach dem angekündigten Termin ausgerichtet haben, sollte dieser Termin als verbindlich gelten, auch wenn sich interne Prioritäten verschieben.

4. Mit dem Link-Header auf die Nachfolgeversion verweisen

Deprecation und Sunset allein sagen einem Client, dass er handeln muss, aber nicht wohin er wechseln soll. Der Link-Header mit der Relation successor-version, ebenfalls Teil des RFC-8594-Ökosystems, verweist direkt auf die URL des Nachfolge-Endpoints, sodass Integratoren die Migration ohne separate Dokumentationssuche starten können.

In der Praxis lohnt sich zusätzlich ein Link-Header mit der Relation deprecation, der auf eine menschenlesbare Erklärungsseite mit Migrationsleitfaden verweist, weil maschinenlesbare Header allein selten ausreichen, um eine vollständige Migration zu planen. Beide Link-Relationen können parallel in derselben Antwort gesetzt werden.

Für Client-SDKs, die Link-Header automatisch auswerten, kann dieser Verweis sogar genutzt werden, um Entwicklern direkt in der IDE einen klickbaren Hinweis auf den Nachfolge-Endpoint anzuzeigen, was die Hürde für eine zeitnahe Migration spürbar senkt, verglichen mit einer rein textuellen Ankündigung in einem Changelog.

5. Wie viel Vorlaufzeit eine faire Abschaltung braucht

Die angemessene Vorlaufzeit zwischen erster Deprecation-Kennzeichnung und tatsächlicher Abschaltung hängt stark von der Nutzerbasis ab: Eine interne API mit wenigen, bekannten Konsumenten kann mit wenigen Wochen Vorlauf auskommen, eine öffentliche API mit tausenden unbekannten Integratoren braucht oft sechs Monate oder länger, um allen Teams realistisch Zeit für die Migration zu geben.

Eine bewährte Praxis ist ein gestufter Prozess: zunächst nur der Deprecation-Header ohne festes Datum, nach einer Beobachtungsphase mit sinkender Nutzung dann Ergänzung um ein konkretes Sunset-Datum mit ausreichendem Vorlauf, und erst nach Erreichen dieses Datums die tatsächliche Abschaltung, idealerweise mit einer Übergangsphase, in der der alte Endpoint noch mit HTTP 410 Gone statt komplettem Verschwinden antwortet.

Bei APIs mit vertraglich fixierten Service-Level-Agreements sollte die Vorlaufzeit zudem explizit im Vertrag verankert werden, damit Integratoren sich nicht auf informelle Zusagen verlassen müssen und im Streitfall ein klarer, überprüfbarer Maßstab existiert.

6. Tatsächliche Nutzung veralteter Endpoints beobachten

Ein Sunset-Datum ohne Kenntnis der tatsächlichen verbleibenden Nutzung ist riskant: Ein Endpoint mit weiterhin hohem Traffic kurz vor dem geplanten Abschalttermin deutet darauf hin, dass viele Integratoren die Warnung übersehen haben, und eine plangemäße Abschaltung würde erhebliche Ausfälle verursachen. Access-Logs, die pro Endpoint und idealerweise pro API-Key die Nutzung tracken, machen sichtbar, welche konkreten Integratoren noch migrieren müssen.

Bei kritischen APIs lohnt sich, betroffene Integratoren anhand der API-Key-Nutzung direkt zu identifizieren und gezielt zu kontaktieren, statt sich ausschließlich auf die HTTP-Header-Kommunikation zu verlassen. Diese proaktive Nachverfolgung reduziert das Risiko, dass die Abschaltung trotz technisch korrekter Kommunikation zu echten Produktionsausfällen bei Integratoren führt.

7. Verhalten nach dem tatsächlichen Abschalttermin

Nach dem Sunset-Datum sollte der Endpoint nicht einfach mit HTTP 404 Not Found antworten, was Integratoren keinen Hinweis auf den Grund gibt, sondern mit HTTP 410 Gone, das explizit signalisiert, dass die Ressource absichtlich und dauerhaft entfernt wurde. Die Antwort sollte weiterhin den Link-Header zur Nachfolgeversion enthalten, damit auch verspätete Integratoren noch den richtigen Migrationsweg finden.

Eine Übergangsphase von einigen Wochen mit HTTP 410 Gone statt eines kompletten Routenverfalls gibt verspäteten Integratoren noch eine klare, maschinenlesbare Fehlermeldung statt eines verwirrenden generischen 404, bevor der Endpoint schließlich vollständig aus dem Routing entfernt wird.

8. Deprecation in der OpenAPI-Spezifikation dokumentieren

Zusätzlich zu den Laufzeit-Headern sollte die OpenAPI-Spezifikation selbst das deprecated-Flag auf Operation-Ebene setzen, damit generierte Client-SDKs und interaktive Dokumentation wie Swagger UI den veralteten Status bereits vor der ersten tatsächlichen Anfrage anzeigen. Viele Codegeneratoren markieren aus deprecated generierte Methoden automatisch mit Sprach-eigenen Deprecation-Annotationen (etwa @deprecated in PHPDoc), was Entwicklerteams schon beim Kompilieren oder in der IDE warnt.

Diese doppelte Kommunikation, sowohl zur Entwicklungszeit über die OpenAPI-Spezifikation als auch zur Laufzeit über HTTP-Header, deckt unterschiedliche Zeitpunkte im Integrationsprozess ab und reduziert die Wahrscheinlichkeit, dass ein Team die Abkündigung komplett übersieht.

Für Teams, die ihre Client-SDKs automatisiert aus der OpenAPI-Spezifikation generieren, lohnt sich zusätzlich ein CI-Check, der bei jedem Build warnt, sobald als deprecated markierte Operationen noch aktiv im eigenen Code aufgerufen werden, statt diese Prüfung ausschließlich manuell durchzuführen.

9. Sunset- und Deprecation-Header im Überblick

Die folgende Tabelle fasst zusammen, welche Header welche Information tragen und wann sie eingesetzt werden.

10. Zusammenfassung

11. FAQ: Sunset & Deprecation: Das Wichtigste auf einen Blick