Wie man einen API-Migrationsleitfaden schreibt

Ein API-Migrationsleitfaden ist das Dokument, das aus einer Breaking Change eine Checkliste macht statt eines Ausfalls: was sich geändert hat, was zu tun ist, und bis wann. Ein Changelog-Eintrag kann eine Breaking Change in zwei Sätzen benennen; ein Migrationsleitfaden ist das, was eine Aufruferin tatsächlich öffnet, wenn diese zwei Sätze sagen „das betrifft dich” und sie genau wissen muss, was zu ändern ist. Den Eintrag ohne Leitfaden zu veröffentlichen ist der Weg, wie eine Aufruferin von einer Breaking Change aus einem Support-Ticket erfährt statt aus dem Dokument, das genau das verhindern sollte.

Was ist ein API-Migrationsleitfaden?

Ein Schritt-für-Schritt-Dokument, das eine Aufruferin von der alten Form einer API zur neuen bringt, geschrieben für jemanden mit bestehendem Code, nicht für jemanden, der noch entscheidet, ob die API überhaupt genutzt wird. Dieser Unterschied zählt: Ein Migrationsleitfaden setzt eine bestehende Integration und bestehenden Produktionsverkehr voraus, weshalb er Rollback, teilweise Migration und die Frage abdecken muss, wie man erkennt, ob die Migration gelungen ist, was ein Leitfaden für eine erste Integration nicht braucht.

Ein Migrationsleitfaden steht meist zwischen den letzten beiden: Eine Deprecation Notice startet eine Uhr, und der Migrationsleitfaden ist das, dem eine Aufruferin folgt, bevor diese Uhr abläuft.

Wann braucht eine Änderung einen Migrationsleitfaden, und nicht nur einen Changelog-Eintrag?

Wenn zwischen dem alten und dem neuen Verhalten mehr als ein Schritt liegt, oder wenn die Änderung genug Aufrufstellen betrifft, dass eine Aufruferin von einem durchgerechneten Beispiel mehr profitiert als von einer Beschreibung. Was ist eine Breaking Change, und wie liefert man sie aus behandelt den Test dafür, ob eine Änderung überhaupt brechend ist; ist die Antwort ja, lautet die zweite Frage, ob die Korrektur eine Ein-Zeilen-Änderung ist oder eine echte Migration. Eine umbenannte Feldbezeichnung kann eine Aufruferin allein aus dem Changelog-Eintrag bewältigen. Eine Änderung an Authentifizierung, Paginierung oder Fehlerbehandlung verdient sich fast immer einen Leitfaden, weil der korrekte Ersatzcode aus einem Ein-Satz-Beschreibung nicht offensichtlich ist.

Was muss ein Migrationsleitfaden enthalten?

Fünf Dinge, und jedes davon auszulassen ist der Weg, wie ein Leitfaden zu einer Seite wird, die eine Aufruferin einmal liest und dann auf Ausprobieren zurückfällt. Den alten Code, gezeigt so, wie er tatsächlich in einem Projekt aussehen würde. Den neuen Code, genauso gezeigt, nicht als abstrakte Beschreibung des Unterschieds. Was bricht, wenn nichts geändert wird, klar gesagt, denn „nichts” ist eine gültige und häufige Antwort, die eine Aufruferin trotzdem ausdrücklich hören muss. Eine Möglichkeit zu prüfen, ob die Migration funktioniert hat, etwa ein Antwortfeld oder ein Statuscode. Und einen Zeitplan: wann das alte Verhalten aufhört zu funktionieren, und ob zwischenzeitlich beide Formen verfügbar sind.

## Migration von Währungsfeldern von Float zu Integer (v3.0.0)

Vorher:
  { "amount": 19.99 }

Nachher:
  { "amount": 1999 }  // kleinste Währungseinheit (Cent)

Was sich ändert: `amount` ist jetzt eine Ganzzahl in der kleinsten
Einheit der Kontowährung. Code, der `amount` als Float liest, liest ab
dem 1.10.2026 einen 100x zu großen Wert.

Prüfen: Nach der Migration sollte eine Belastung von 19,99 € als
`amount: 1999` gelesen werden, nicht als `amount: 19.99`.

Zeitplan: v2 liefert weiterhin Floats bis zum 15.1.2027. v3 liefert
Ganzzahlen ab dem Start. Beide Versionen sind jetzt live.

Jedes dieser fünf Dinge beantwortet eine Frage, die eine Aufruferin sonst raten oder dem Support stellen müsste, und genau das sind die Kosten, die ein Migrationsleitfaden tatsächlich spart.

Wer sollte ihn schreiben, und wann?

Wer die Änderung entworfen hat, im selben Moment, in dem sie ausgeliefert wird, nicht ein Support-Team, das ihn später aus Tickets rekonstruiert. Wer die Entscheidung getroffen hat, weiß, auf welche Teile des alten Verhaltens sich niemand hätte verlassen sollen und welche ein versehentlicher Vertrag waren; ein später von jemandem ohne diesen Kontext geschriebener Leitfaden neigt dazu, entweder das Offensichtliche zu überklären oder genau den einen Randfall zu verpassen, der tatsächlich Leute bricht. Der Leitfaden und der Changelog-Eintrag, der die Breaking Change ankündigt, sollten gemeinsam erscheinen, wobei der Eintrag zum Leitfaden verlinkt statt ihn zu wiederholen.

Wie hängt das mit Versionierung und dem API-Changelog zusammen?

Direkt: Ein Migrationsleitfaden ist die ausführliche Version dessen, was ein MAJOR-Eintrag in Semantic Versioning und dein Changelog nur in einem Satz zusammenfasst. Der Changelog-Eintrag sagt, dass eine Änderung brechend ist und grob, was sich geändert hat; der Migrationsleitfaden ist der Link, den dieser Eintrag tragen sollte. API-Changelog: was hinein gehört und wer es liest listet den Migrationsleitfaden als eines von fünf Dokumenten, die eine API pflegt, jedes beantwortet eine andere Frage; dies ist das, das „wie komme ich tatsächlich von A nach B” beantwortet, und es verdient sich seine eigene Seite genau deshalb, weil diese Antwort für einen Changelog-Eintrag meist zu lang ist.

Wie lange sollte ein Migrationsleitfaden veröffentlicht bleiben?

Mindestens so lange, wie das alte Verhalten erreichbar ist, und idealerweise darüber hinaus. Eine Aufruferin, die achtzehn Monate zu spät migriert, nachdem sie drei Deprecation Notices ignoriert hat, braucht den Leitfaden immer noch, und ihn am Tag abzuschalten, an dem das alte Verhalten abgeschaltet wird, garantiert nur, dass die Aufruferin, die ihn am dringendsten braucht, ihn nicht findet. Halte ihn unter einer stabilen URL und aktualisiere den Zeitplan-Abschnitt, statt die Seite zurückzuziehen. Stripes eigener Upgrade-Leitfaden ist ein öffentliches Beispiel für dieses Muster: eine Seite, Release für Release aktuell gehalten, statt eines neuen Dokuments pro Version, das veraltet, sobald das nächste erscheint. Euer eigener Leitfaden gehört an einen ebenso auffindbaren Ort, neben die Docs, die eine Aufruferin ohnehin schon liest, statt in einem Blog-Archiv vergraben zu sein.

FAQ

Braucht jede Breaking Change einen Migrationsleitfaden? Nein. Eine Änderung, die eine Aufruferin allein aus dem Changelog-Eintrag beheben kann, wie ein einzelnes umbenanntes Feld mit offensichtlichem Ersatz, braucht keinen eigenen Leitfaden. Eine Änderung, die mehrere Aufrufstellen betrifft oder ein durchgerechnetes Beispiel braucht, schon.

Sollte ein Migrationsleitfaden bei der API-Dokumentation liegen oder im Changelog? Bei der Dokumentation, verlinkt aus dem Changelog-Eintrag. Der Changelog-Eintrag ist das, was eine Abonnentin zuerst sieht; der Leitfaden ist das, was sie braucht, sobald sie sich entschieden hat zu handeln, und er gehört neben das Referenzmaterial, das eine Aufruferin bereits nutzt.

Was ist der Unterschied zwischen einem Migrationsleitfaden und einer Deprecation Notice? Eine Deprecation Notice sagt, dass etwas wegfällt und bis wann. Ein Migrationsleitfaden sind die Anweisungen, was dagegen zu tun ist. Eine Deprecation Notice ohne verlinkten Migrationsleitfaden sagt einer Aufruferin eine Frist, ohne ihr zu sagen, wie sie einzuhalten ist.

Sollten altes und neues Verhalten während eines Migrationsfensters beide dokumentiert sein? Ja, wenn möglich auf derselben Seite, damit eine Aufruferin genau sieht, was sich geändert hat, statt es aus zwei getrennten, zu unterschiedlichen Zeiten geschriebenen Dokumenten zusammenzusetzen.

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