API-Changelog: was hinein gehört und wer es liest

Ein API-Changelog ist das datierte Protokoll jeder Änderung, die ein Aufrufer bemerken könnte, geschrieben für die Leute, die gegen die API integrieren, nicht für das Team, das sie ausliefert. Dieses Publikum macht es zu einem anderen Dokument als einen Produkt-Changelog: Der Leser entscheidet, ob sein Code nächsten Monat noch läuft. Die meisten scheitern auf dieselbe Art, indem sie eine gefilterte Kopie eines internen Release-Feeds sind, sodass ein entferntes Feld neben einem Text-Fix mit demselben Gewicht steht und keins von beiden gelesen wird.

Was ist ein API-Changelog?

Es ist das öffentliche, datierte Protokoll von Änderungen an einer Schnittstelle, gegen die andere Leute Code geschrieben haben. Der brauchbare Test dafür, ob etwas hineingehört, hat nichts damit zu tun, wie groß die Änderung intern war. Er fragt, ob ein korrekter Aufrufer, letztes Jahr geschrieben und seither unverändert, sich dadurch anders verhalten könnte. Dieser Test lässt manche sehr kleinen Änderungen zu und schließt manche sehr großen aus.

Alles unten geht davon aus, dass der Aufrufer außerhalb des Unternehmens sitzt und effektiv nur über dieses Dokument erreichbar ist. Wenn der Aufrufer ein anderes Team im selben Haus ist, ändert sich die Rechnung genug, um eine eigene Behandlung zu brauchen; interne API-Changelogs behandelt, was dieses Publikum stattdessen braucht.

Wie man einen API-Migrationsleitfaden schreibt behandelt dieses letzte Dokument vollständig; kurz gesagt ist es das, worauf ein Breaking-Change-Eintrag verlinken sollte, statt es zu ersetzen.

Die fünf sind separate Dokumente mit separaten Lebenszyklen. Eine Deprecation Notice ist ein Versprechen mit Datum und gehört auch in den Changelog, aber ein Changelog-Eintrag wird einmal geschrieben, während eine Deprecation bis zu ihrem Sunset verfolgt wird. Sie zusammenzulegen ist, warum Sunsets verpasst werden.

Was gehört in einen einzelnen Eintrag?

Sechs Dinge, und die ersten drei fehlen meistens. Die Änderung, formuliert in Begriffen der Anfrage oder Antwort statt der internen Komponente. Ob sie einen korrekten Aufrufer bricht. Was der Aufrufer tun muss, einschließlich “nichts”. Das Datum, an dem sie wirksam wurde. Die betroffene Version oder Versionen. Ein Link zum Migrationsleitfaden, falls einer existiert.

Ein Eintrag, der sagt “Accounts-Endpunkt verbessert”, scheitert an allen sechs. Ein Eintrag, der sagt “das Feld accounts.type gibt jetzt individual zurück, wo vorher personal stand; bestehende Werte bleiben für Accounts unverändert, die vor dem 2. September erstellt wurden; keine Aktion nötig, außer man vergleicht den String” beantwortet alle sechs in einem Satz.

Kategorisiert Einträge nach Konsequenz, nicht nach Abteilung. Drei Labels tragen fast den ganzen Wert: Breaking, Additive und Fixed. Semantic Versioning definiert die ersten beiden bereits präzise, und diese Definitionen zu übernehmen statt eigene zu erfinden bedeutet, dass ein Leser, der Semver kennt, eure Labels kennt. Keep a Changelog liefert eine längere Liste, falls gewünscht, und seine zentrale Regel gilt hier stärker als irgendwo sonst: Das Log ist für Menschen, und ein Dump von Commit-Titeln ist keins.

Wie unterscheidet sich ein API-Changelog von Release Notes?

Release Notes beschreiben, was das Produkt jetzt kann. Ein API-Changelog beschreibt, was der Vertrag jetzt ist. Dieselbe ausgelieferte Arbeit produziert oft einen Eintrag in beiden, anders formuliert, weil die Publika unterschiedliche Dinge brauchen: Ein neues Exportformat ist für einen Nutzer ein Feature und für einen Aufrufer, der auf diesem Feld schaltet, ein neuer Enum-Wert.

Die praktische Konsequenz ist, dass die beiden nicht derselbe Feed mit anderem Styling sein können. Ein Aufrufer, der alles abonniert, was ihr ausliefert, wird sich abmelden und dann den Breaking Change verpassen. Wenn ihr einen Feed veröffentlicht, filtert ihn; wenn ihr zwei veröffentlicht, macht den API-Feed enger und lasst nie einen Marketing-Eintrag hinein. Wir vergleichen beide Formen direkt in Changelog vs. Release Notes.

Wo sollte ein API-Changelog leben?

Neben der Referenzdokumentation, auf einer stabilen URL, mit jedem Eintrag einzeln adressierbar über ein Fragment oder einen eigenen Pfad. Aufrufer verlinken Einträge in Incident Reviews und internen Tickets, und ein Eintrag, der nicht verlinkbar ist, wird stattdessen als Screenshot eingefügt.

Veröffentlicht es zusätzlich zur Seite als maschinenlesbare Ausgabe. Ein JSON-Feed nach der JSON-Feed-Spezifikation oder ein RSS-Feed kostet nichts, sobald die Einträge strukturierte Daten sind, und ist das, was einen Kunden eure Änderungen in seinen eigenen Release-Prozess einbauen lässt. Das entscheidet auch, ob überhaupt jemand darauf aufbaut. GitHub dokumentiert seine REST-API-Versionen direkt neben der Referenz, aus demselben Grund: Die Versionspolitik ist Teil der Schnittstelle.

Wie sieht ein guter Eintrag in der Praxis aus?

Drei Einträge aus derselben Woche, in der oben beschriebenen Form:

2026-09-02  Breaking  v2
  `POST /invoices` lehnt jetzt eine `currency` ab, die nicht mit der
  Kontowährung des Kunden übereinstimmt, und gibt 422 statt stiller
  Umrechnung zurück. Aufrufer, die sich auf die Umrechnung verlassen haben,
  müssen die Kontowährung senden. Betrifft nur v2; v1 bleibt bis zum
  Sunset am 2027-01-15 unverändert.

2026-09-02  Additive  v1, v2
  `Invoice` erhält einen `settled_at`-Zeitstempel, null bis die Rechnung
  beglichen ist. Keine Aktion nötig. Clients, die unbekannte Felder
  ablehnen, sollten aktualisiert werden.

2026-08-31  Fixed  v2
  `GET /invoices?status=` gab eine leere Seite zurück statt eines 400 bei
  unbekanntem Status. Gibt jetzt 400 mit den akzeptierten Werten zurück.
  Aufrufer mit einem Tippfehler sahen vorher keine Ergebnisse, jetzt einen
  Fehler.

Der dritte ist die Art, die am häufigsten weggelassen wird, weil er intern ein Bugfix ist. Für einen Aufrufer, der einen Retry um diese leere Seite gebaut hat, ist es eine Verhaltensänderung, und der Eintrag ist das, was das Support-Ticket verhindert. Das Label sagt Fixed, und der Text sagt, was ein Aufrufer bemerken könnte, was die Unterscheidung ist, die das Log ehrlich hält, ohne jeden Fix zu einem Breaking Change aufzublasen.

Wie abonnieren Aufrufer es?

Gebt ihnen mehr als einen Kanal, weil sie unterschiedliche Aufgaben haben. Einen Feed für den Entwickler, der alles will. E-Mail für die Person, die nur Breaking Changes will. Response-Header für den Code selbst, der einzige Abonnent, der nie vergisst zu prüfen: Der Sunset-Header aus RFC 8594 legt das Ablaufdatum in die Antwort, wo eine Client-Library es loggen kann.

Der Kanal, den die meisten Teams auslassen, ist der direkte. Wenn ein Aufrufer letzte Woche das Feld genutzt hat, das ihr ändert, wisst ihr, wer er ist, und eine E-Mail an diese Accounts ist mehr wert als jede Menge Broadcast. Das ist dieselbe Disziplin wie beim Schließen des Feedback-Loops, angewandt auf eine Änderung, die niemand angefragt hat: Die Betroffenen werden einzeln informiert, alle anderen bekommen den Feed. Ein Webhook ist ein vierter Kanal mit eigenem Fehlerbild, das man kennen sollte, bevor man sich darauf verlässt: Webhook-Changelogs behandelt, warum eine Payload-Änderung dort lautlos bricht, ohne Aufrufer, der die neue Form ablehnen könnte.

Wie schreibt man einen Eintrag für einen Breaking Change?

Führt mit dem Bruch, nicht mit dem Grund. Ein Aufrufer, der zehn Einträge überfliegt, muss im ersten Satzteil wissen, ob dieser hier ihm Arbeit kostet. Dann das Datum, die betroffenen Versionen, die Migration, und die Frist, falls das alte Verhalten wegfällt statt sich zu ändern.

Packt denselben Inhalt in die Deprecation Notice, den Response-Header und die direkte E-Mail, konsistent formuliert, und gebt allen vieren dasselbe Datum. Abweichung zwischen ihnen ist der Fehler, der eine geplante Änderung in einen Vorfall verwandelt, weil der Aufrufer, der nur eines davon gelesen hat, zum falschen Datum handelt. Was ist ein Breaking Change behandelt die Entscheidung selbst, und wie man eine API abkündigt behandelt den Zeitplan danach.

In changeloop wird eine API-Änderung zu einem Eintrag, wenn der Pull Request gemerged wird, eine Person den Entwurf bearbeitet und freigibt, und der Eintrag zum selben Moment im Feed und im Widget veröffentlicht wird, in dem ein Aufrufer, dessen Widget-Feedback zu dem GitHub-Issue wurde, das der Pull Request schließt, auf diesem Issue informiert wird. Der Review-Schritt ist der Teil, der hier zählt: Ein API-Changelog ist ein Vertragsdokument, und kein Entwurf sollte einen Aufrufer erreichen, ohne dass ein Mensch ihn gelesen hat.

FAQ

Braucht jede API-Änderung einen Changelog-Eintrag? Jede Änderung, die ein korrekter Aufrufer bemerken könnte, ja, auch solche, die ihr für intern haltet. Änderungen ohne beobachtbaren Effekt auf Anfrage oder Antwort nicht, und sie hinzuzufügen trainiert Leser zum Überfliegen.

Sollte der API-Changelog in den Docs oder auf der Marketing-Seite leben? In den Docs, direkt neben der Referenz. Der Leser ist meist schon dort, und ein Changelog auf der Marketing-Seite gewinnt tendenziell ein Publikum, für das er nicht geschrieben wurde.

Wie weit sollte er zurückreichen? Unbegrenzt. Einträge werden Jahre später in Incident Reviews zitiert, und ein gekürztes Log bricht diese Links. Paginiert, statt zu kürzen.

Brauche ich einen separaten Changelog pro API-Version? Nein, ein Log mit einem Versionsfeld pro Eintrag ist leichter zu lesen und zu durchsuchen. Filtern nach Version ist ein Feature der Seite, kein Grund, das Dokument zu trennen.

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