Wie man eine API abkündigt, ohne Entwickler zu verlieren

Eine API abzukündigen bedeutet, anzukündigen, dass etwas heute noch funktioniert und an einem genannten Datum aufhört, und dann beide Hälften dieses Versprechens zu halten. Die meisten Abkündigungen scheitern an der zweiten Hälfte: Das Datum verschiebt sich still, oder es kommt, und die Aufrufer, die die Ankündigung nie gesehen haben, erfahren es von einem Fehler. Eine Abkündigung ist fertig, wenn jeder betroffene Aufrufer entweder migriert wurde oder ihm einzeln gesagt wurde, dass er es nicht ist.

Was ist API-Abkündigung?

Deprecation ist die Zeitspanne zwischen der Ankündigung, dass ein Endpunkt, ein Feld oder eine Version verschwindet, und der tatsächlichen Entfernung. In dieser Zeit funktioniert das alte Verhalten weiter, die Dokumentation sagt, dass es geht, und jede Antwort trägt eine maschinenlesbare Warnung. Die Entfernung ist das getrennte, spätere Ereignis, oft Sunset genannt. Die beiden werden vermischt, und genau in dieser Vermischung passiert der Schaden: “deprecated” fängt an, “könnte schon weg sein” zu bedeuten, und Aufrufer vertrauen keinem der beiden Wörter mehr.

Wie lang sollte eine Deprecation-Periode sein?

Lang genug, damit ein Aufrufer es erfährt und die Arbeit erledigt, gemessen ab dem Zeitpunkt, an dem die Ankündigung ihn erreicht hat, nicht ab dem, an dem ihr sie geschrieben habt. Neunzig Tage sind die übliche Untergrenze für eine öffentliche Web-API. Zwölf Monate sind üblich für alles, was in Software eingebettet ist, die Endnutzer installieren, weil der Fix auch durch deren Release-Prozess laufen muss. Googles Versionierungsleitfaden AIP-185 verlangt eine angemessene Übergangsfrist und empfiehlt 180 Tage sogar schon vor dem Entfernen von Beta-Funktionen, und Kubernetes dokumentiert seine Abkündigungsrichtlinie in Release-Zählungen statt in Monaten, was die richtige Einheit ist, wenn eure Aufrufer nach Version aktualisieren.

Wählt eine Periode, schreibt sie als Richtlinie auf, und hört auf, sie pro Änderung neu zu entscheiden. Eine veröffentlichte Richtlinie macht aus jeder Abkündigung eine Regelanwendung statt eine Verhandlung.

Die Deprecation-Richtlinie schriftlich festzuhalten deckt den Anfang des Fensters ab; API-Version abschalten behandelt die separate Ankündigung, die am Ende nötig ist, sobald die Periode tatsächlich abläuft und die Version aufhört zu funktionieren.

Der Deprecation-Zeitplan

Vier Daten, alle am ersten Tag zusammen angekündigt. Jedes ist ein eigener Changelog-Eintrag, wenn es eintritt, sodass die Geschichte viermal erzählt wird für alle, die nur den Changelog lesen.

1. Ankündigen. Der Eintrag sagt, was abgekündigt wird, warum, was es ersetzt, und das Sunset-Datum. Die Dokumentation für das Alte bekommt ein Banner, das zur Migration verlinkt. Antworten bekommen die unten beschriebenen Header.
2. Erinnern, auf halber Strecke. Ein zweiter Eintrag, plus eine direkte Nachricht an jeden Aufrufer, der das alte Verhalten noch nutzt. Das ist der Schritt, der Nutzungsdaten braucht: Könnt ihr nicht auflisten, wer den abgekündigten Endpunkt noch aufruft, könnt ihr das nicht tun, und das lohnt sich zu beheben, bevor die nächste Abkündigung ansteht.
3. Kurz vorher abschalten (Brownout). Für ein kurzes Fenster, eine Stunde oder einen Tag, Fehler für das alte Verhalten zurückgeben, dann wiederherstellen. Aufrufer, die jede Ankündigung verpasst haben, erfahren es jetzt, während noch Zeit ist. GitHub nutzte geplante Brownouts vor der Abschaltung der Passwort-Authentifizierung für die API, und das ist der wirksamste einzelne Schritt in dieser Liste.
4. Sunset. Entfernen. Der Fehler, der es ersetzt, nennt den Ersatz und verlinkt den Migrationsleitfaden. Behaltet den Fehler lange bei; ein 404 sagt einem Aufrufer nichts.

Was sollte eine Deprecation-Ankündigung sagen?

Eine Deprecation-Ankündigung sagt, was verschwindet, wann es aufhört, was stattdessen zu nutzen ist, und wer betroffen ist. Hier die Form, ausgefüllt:

GET /v1/reports/daily ist abgekündigt und funktioniert ab 1. März 2027 nicht mehr. Ersetzt durch GET /v2/reports?granularity=day, das dieselben Daten mit stabilem Schema und Paginierung liefert. Betrifft die 214 Integrationen, die den v1-Endpunkt in den letzten 30 Tagen aufgerufen haben; ist eure darunter, erhaltet ihr diese Ankündigung auch per E-Mail. Migrationsleitfaden: [Link]. Bis 1. März 2027 ändert sich nichts. Ab diesem Datum gibt der v1-Endpunkt 410 Gone zurück, mit einem Link zu diesem Eintrag.

Jeder Satz trägt etwas, das die Leserin braucht. Die Anzahl der betroffenen Integrationen sagt jeder Leserin, ob sie weiterlesen sollte. “Bis dahin ändert sich nichts” ist der Satz, der die Nicht-Betroffenen den Tab schließen lässt. Die Seite Changelog-Beispiele sammelt Einträge von Teams, die diese Form konsequent schreiben, und es lohnt sich, drei davon zu lesen, bevor man den ersten eigenen schreibt.

Welche Header sollte ein abgekündigter Endpunkt senden?

Sendet Deprecation, Sunset und einen Link zum Nachfolger, in jeder Antwort des abgekündigten Endpunkts, ab dem Tag der Ankündigung. Der Deprecation-Header trägt das Datum, an dem die Abkündigung in Kraft trat; der Sunset-Header trägt das Datum, an dem der Endpunkt aufhört zu antworten; Link: <url>; rel="successor-version" zeigt auf den Ersatz.

HTTP/1.1 200 OK
Deprecation: @1756425600
Sunset: Mon, 01 Mar 2027 00:00:00 GMT
Link: <https://api.example.com/v2/reports>; rel="successor-version"
Link: <https://example.com/changelog/daily-reports>; rel="deprecation"

Die meisten Aufrufer werden die Header selbst nie lesen. Ihr Wert liegt darin, dass der HTTP-Client, das Gateway oder das Monitoring eines Aufrufers es kann, was aus eurer Abkündigung einen Alert auf ihrer Seite macht statt einer Seite auf eurer. Von euch ausgelieferte SDKs sollten eine Warnung loggen, wenn sie einen sehen.

Wer wurde informiert, und woher wisst ihr das?

Das ist der Schritt, der entscheidet, ob der Sunset ruhig abläuft oder zum Support-Vorfall wird, und er ist der schwierigste allein mit einem Changelog. Ein Changelog-Eintrag informiert jeden, der den Changelog liest. Eine Abkündigung muss die konkreten Menschen erreichen, deren Code scheitern wird, und der übliche Weg, sie zu finden, sind dieselben Nutzungsdaten, die die Erinnerung auf halber Strecke braucht: die API-Keys, Apps oder Konten, die das abgekündigte Verhalten kürzlich aufgerufen haben.

Unser Loop: Der Eintrag wird aus dem Pull Request entworfen, der die Abkündigung hinzufügt, ein Mensch prüft Formulierung und Datum, und sobald er veröffentlicht ist, ist der Eintrag selbst die Benachrichtigung. Wessen Widget-Feedback zu dem Problem oder Wunsch nach dem Ersatz zu einem GitHub-Issue wurde, das der Pull Request schließt, bekommt auf diesem Issue einen Kommentar, dass es ausgeliefert wurde, mit Link zum Eintrag. Feed und Widget bedienen alle anderen mit demselben Eintrag, zusammen mit jedem anderen Eintrag im API-Changelog. Was wir nicht tun: die Abkündigung “ausgeliefert” werden lassen, bevor ein Mensch sie freigegeben hat; eine Ankündigung mit falschem Datum ist schlimmer als keine.

Egal welche Werkzeuge ihr habt, die Frage, die ihr am Sunset-Tag beantworten können müsst, ist: Welche Aufrufer haben das letzte Woche noch genutzt, und wem davon haben wir es direkt gesagt? Ist die Antwort “wir haben darüber gepostet”, ist der Sunset nicht bereit.

Was ist der Unterschied zwischen Abkündigung und Versionierung?

Versionierung ist, wie man das alte Verhalten verfügbar hält, während das neue existiert; Abkündigung ist, wie man das alte in den Ruhestand schickt. Eine neue API-Version ohne Abkündigungsrichtlinie für die vorherige ist eine Verpflichtung, beide für immer zu betreiben. Eine Abkündigung ohne Versionierung ist ein Breaking Change mit Verzögerung. Man braucht beides, und die Version ist die leichtere Hälfte. GraphQL ist die Ausnahme, die es zu nennen lohnt: Meist gibt es überhaupt keine Versionsnummer zu erhöhen, und GraphQL-Schema-Abkündigung behandelt, wie ein einzelnes geteiltes Schema ein Feld stattdessen mit einer Direktive abkündigt.

FAQ

Sollte ein abgekündigter Endpunkt exakt wie vorher weiterfunktionieren? Ja, bis zum Sunset-Datum. Die einzig erlaubten Änderungen sind die hinzugefügten Header und, gegen Ende, ein geplanter, im Voraus angekündigter Brownout.

Welchen Statuscode sollte ein im Ruhestand befindlicher Endpunkt zurückgeben? 410 Gone, mit einem Body und einem Link-Header zum Ersatz und zum Changelog-Eintrag. 404 sagt, die URL habe nie existiert, was falsch und unhilfreich ist.

Kann eine Deprecation-Periode verkürzt werden? Nur aus Sicherheitsgründen. Ist das alte Verhalten ausnutzbar, sagt das, verkürzt die Periode, und informiert jeden betroffenen Aufrufer direkt, statt euch auf den Changelog zu verlassen.

Muss ich ein Feld abkündigen, oder nur ganze Endpunkte? Felder, Parameter, Enum-Werte, Standardwerte und Header brauchen alle dieselbe Behandlung, weil jedes davon einen korrekten Aufrufer brechen kann. Ein entferntes Feld ist die häufigste Abkündigung und die am öftesten übersprungene.

Die technischen Aussagen in diesem Artikel wurden nicht unabhängig geprüft. Wenn etwas nicht stimmt, sagen Sie es uns, und wir korrigieren es.

Mehr bei changeloop: Entwicklerdokumentation, Changelog-Beispiele