API Deprecation: Definition, Best Practices, Beispiele

Was ist API-Deprecation?

API-Deprecation (Veralten einer API) ist der formale Prozess, einen Endpoint, eine Version, einen Parameter oder ein Response-Feld auslaufen zu lassen. Der veraltete Teil funktioniert für einen angekündigten Zeitraum weiter, während Nutzer erfahren, was sie stattdessen verwenden sollen. Am Ende wird er entfernt, das nennt man Sunset, und wer ihn weiter aufruft, bekommt Fehler.

Es ist der Vertrag zwischen API-Anbieter und Nutzern: Das ändert sich, hier ist das Datum, hier ist der Ersatz.

Der Deprecation-Ablauf

Deprecation in HTTP signalisieren

Zwei Standard-Response-Header machen Deprecation maschinenlesbar. Deprecation (RFC 9745, März 2025) besagt, dass die Ressource veraltet ist oder sein wird, als Datum in der Form @ plus Unix-Sekunden. Sunset (RFC 8594) nennt, wann sie voraussichtlich nicht mehr antwortet, als HTTP-Datum, das nicht vor dem Deprecation-Datum liegen sollte. Ein Link-Header mit rel="deprecation" kann auf die Dokumentation zeigen.

HTTP/1.1 200 OK
Deprecation: @1780272000
Sunset: Tue, 01 Dec 2026 00:00:00 GMT
Link: <https://api.example.com/docs/v1-sunset>; rel="deprecation"; type="text/html"
Content-Type: application/json

Beide Header sind Hinweise. Sie ändern nichts am Verhalten des Endpoints, und Clients profitieren nur, wenn etwas sie auswertet. Kündigen Sie daher zusätzlich per E-Mail und in der Doku an.

Was veralten kann

• Eine ganze API-Version, etwa v1 zugunsten von v2.
• Ein einzelner Endpoint, zum Beispiel einer, der durch einen neuen Pfad ersetzt wird.
• Ein Request-Parameter oder ein Response-Feld, etwa created ersetzt durch created_at.
• Eine Authentifizierungsmethode, etwa API-Keys zugunsten von OAuth 2.0.
• Ein Webhook-Event-Typ oder eine SDK-Methode.

Best Practices

• Früh ankündigen. Geben Sie Nutzern genug Zeit, die Arbeit einzuplanen. Eine allgemeingültige Zahl gibt es nicht: GitHub unterstützt zum Beispiel eine frühere REST-API-Version mindestens 24 Monate nach Erscheinen einer neuen.
• Migrationspfad dokumentieren. Zeigen Sie die Zuordnung alt zu neu mit Codebeispielen, nicht nur "nutzen Sie die neue API".
• Header und Changelog nutzen. Machen Sie die Änderung für Maschinen und Menschen auffindbar.
• Nutzer direkt kontaktieren. Schreiben Sie Kontoinhaber an und zeigen Sie einen Hinweis im Produkt. Kaum jemand liest einen Blog.
• Nachverfolgen, wer die alte Version noch aufruft. Protokollieren Sie die Nutzung pro Endpoint und Nutzer (API-Key, OAuth-Client), um die richtigen Leute zu erreichen.
• Zuerst den Ersatz ausliefern. Betreiben Sie alt und neu parallel und halten Sie SDKs aktuell.
• Die Abschaltung proben. Ein kurzer, angekündigter Brownout, bei dem die alte Version eine Weile ausfällt, bringt vergessene Clients vor der echten Abschaltung zum Vorschein.
• Nach dem Sunset 410 Gone liefern. MDN beschreibt es so: Die Ressource ist nicht mehr verfügbar, wahrscheinlich dauerhaft. Nutzen Sie 404, wenn Sie nicht wissen, ob es dauerhaft ist.

Häufige Fehler

• Stilles Entfernen. Keine Ankündigung, verärgerte Kunden.
• Kein Migrationsleitfaden. Nutzer müssen den Unterschied selbst herausfinden.
• Ein Zeitraum, der kürzer ist als der Release-Zyklus Ihrer Kunden. Teams, die quartalsweise ausliefern, schaffen es nicht in wenigen Wochen.
• Ein noch genutztes Feld entfernen. Prüfen Sie vorher die Nutzung.
• SDKs und Doku vergessen. Sie schicken Leute weiter zur alten Version.
• Deprecation ohne Ersatz. Nutzer haben keine Alternative.
• Nur im Blog ankündigen. Ergänzen Sie Header, E-Mail und Hinweise im Produkt.

Beispiele aus echten APIs

GitHub-REST-API. Versionen sind nach Datum benannt und werden über den Header X-GitHub-Api-Version gewählt. Requests ohne ihn nutzen 2022-11-28, und bei Erscheinen einer neuen Version bleibt die vorherige mindestens 24 Monate unterstützt (GitHub-Doku).

GitHub-GraphQL-API. GitHub kündigt Breaking Changes am Schema mindestens drei Monate im Voraus an und setzt sie am ersten Tag eines Quartals um. Anstehende Entfernungen stehen auf der Seite zu Breaking Changes (GitHub-Doku).

Stripe. Requests nutzen die Standard-API-Version des Kontos, sofern Sie sie nicht mit dem Header Stripe-Version überschreiben, sodass Sie upgraden, wenn Sie bereit sind. Seit dem Release 2024-09-30 liefert Stripe monatliche Versionen ohne Breaking Changes und zweimal im Jahr ein Major-Release mit Breaking Changes (Stripe-Doku).

Testen und Überwachen im Deprecation-Zeitraum

Solange zwei Versionen parallel laufen, prüfen Sie beide. API-Tests, die alte und neue Responses vergleichen, fangen Verhaltensabweichungen ab, bevor es Ihre Nutzer tun, und die Anleitung zum Import von cURL, HAR, Postman und OpenAPI zeigt, wie Sie vorhandene Requests in Lasttests verwandeln. Das LoadFocus API-Monitoring kann pro Endpoint und Version einen Check ausführen, Statuscode, Header und Body prüfen und Sie alarmieren, wenn der Ersatz ausfällt oder langsamer wird. Kostenlose Checks laufen alle 5 Minuten.

Testen Sie die neue Version außerdem mit dem gemeinsamen Traffic beider Versionen, denn den trägt sie nach dem Sunset. LoadFocus Lasttests führen dafür JMeter- und k6-Skripte aus.

Häufige Fragen: API-Deprecation

Wie lang sollte ein Sunset-Zeitraum sein?

Das hängt von Ihren Nutzern ab. Öffentliche APIs vieler Teams brauchen mehr Zeit als eine interne API mit wenigen bekannten Clients. GitHub unterstützt zum Beispiel eine frühere REST-API-Version mindestens 24 Monate. Ermitteln Sie, wie lange Ihre langsamsten Nutzer brauchen, und planen Sie Reserve ein.

Was ist der Unterschied zwischen Deprecation und Sunset?

Deprecation ist die Ankündigung: Es funktioniert noch, aber bauen Sie nicht darauf auf. Sunset ist das Datum, an dem es nicht mehr funktioniert.

Sollte ich meine API versionieren?

Ja, sobald jemand außerhalb Ihres Teams davon abhängt. URL-Versionen wie /v1/ sind am einfachsten zu sehen und zu testen. Header- oder datumsbasierte Versionen, wie GitHub und Stripe sie nutzen, halten URLs stabil, sind aber fehleranfälliger.

Welchen HTTP-Status sollte ein abgeschalteter Endpoint liefern?

410 Gone ist am klarsten. MDN weist darauf hin, dass Clients Requests an einen 410 nicht wiederholen sollen und dass 404 die Wahl ist, wenn Sie nicht wissen, ob die Entfernung dauerhaft ist.

Wie finde ich heraus, wer einen veralteten Endpoint noch aufruft?

Protokollieren Sie jeden Request mit einer Nutzerkennung wie API-Key oder OAuth-Client-ID und zählen Sie die Aufrufe pro Nutzer und Tag. Kontaktieren Sie zuerst die intensivsten Nutzer.

Ist das Hinzufügen eines Felds ein Breaking Change?

In der Regel nicht, deshalb brauchen additive Änderungen selten eine Deprecation. Ein Feld zu entfernen, umzubenennen oder seine Bedeutung zu ändern schon.