Interne API-Changelogs: Was sich für das andere Team ändert
5 Min. Lesezeit
Jeder andere Artikel in diesem Hub geht davon aus, dass der Aufrufer einer API außerhalb des Unternehmens sitzt: die Entwicklerin einer Kundin, eine Partnerin, jemand, der die Docs selbst gefunden hat. Viele APIs haben einen ganz anderen Aufrufer, ein Team im Nachbarraum oder zwei Stockwerke weiter, und das ändert die Rechnung dafür, was ein Changelog ihm schuldet, weil eine Slack-Nachricht es erreicht und normalerweise nie ein Support-Ticket eröffnet wird. Die meisten Teams schließen daraus, dass interne APIs kein Changelog brauchen. Was sie tatsächlich brauchen, ist ein anderes.
Was macht das Changelog einer internen API anders als das einer öffentlichen?
Das Publikum ist direkt erreichbar, was den Hauptgrund entfernt, warum die meisten öffentlichen API-Changelogs existieren: das Senden an Aufrufer, die man nicht einzeln kontaktieren kann. Das Team, dem eine interne API gehört, kennt meist genau, welche anderen Teams sie aufrufen, manchmal bis zum einzelnen Service. Das macht eine gezielte Nachricht, keinen öffentlichen Feed, zum natürlichen Standard, und genau deshalb landen interne APIs so oft ganz ohne Changelog: Das besitzende Team schreibt die zwei oder drei Teams an, an die es sich erinnert, in der Annahme, dass das alle abdeckt.
| Öffentliches API-Changelog | Internes API-Changelog | |
|---|---|---|
| Wer liest es | Jeder externe Aufrufer, meist nicht direkt erreichbar | Eine kleine, meist bekannte Menge interner Teams |
| Standardkanal | Eine Seite und ein Feed | Eine Nachricht an die aufrufenden Teams, idealerweise auch eine Seite |
| Größtes Risiko | Ein Aufrufer verpasst den Eintrag komplett | Das besitzende Team vergisst einen Aufrufer, an den es sich nicht erinnert |
| Was “wir wissen nicht, wer uns aufruft” ersetzt | Nichts; breit veröffentlichen | Ein echtes, aktuell gehaltenes Verzeichnis der Aufrufer |
Warum bricht “wir sagen einfach den Teams Bescheid, die uns aufrufen” zusammen?
Weil die Menge der Aufrufer nie so klein oder so statisch ist, wie das besitzende Team sich erinnert. Ein für eine Konsumentin gebauter Service bekommt sechs Monate später einen zweiten Aufrufer, durch eine nie angekündigte Integration, und die gedankliche Liste “wer ruft uns auf” des besitzenden Teams ist jetzt falsch, ohne dass es jemand bemerkt. Das Versagen ist gewöhnlich und häufig, das Standardergebnis, sich auf Erinnerung statt auf einen Datensatz zu verlassen, kein Zeichen dafür, dass irgendwer nachlässig war. Was ist ein Breaking Change behandelt, wie man entscheidet, ob eine Änderung überhaupt als Breaking Change zählt; der interne Fall fügt eine zweite, schwierigere Frage obendrauf, nämlich zu wissen, wen man informieren muss.
Braucht eine interne API überhaupt eine Changelog-Seite im öffentlichen Stil?
Meist ja, auch wenn der primäre Kanal direkt ist. Eine Seite gibt der direkten Nachricht etwas zum
Verlinken, damit die Benachrichtigung kurz bleiben kann (“Breaking Change bei /v2/accounts,
Details hier”) statt zu versuchen, die volle Erklärung in einer Chat-Nachricht unterzubringen, die
weggescrollt wird. Sie wird auch zu dem, was ein neues Team, oder eines, das die direkte Nachricht
verpasst hat, nachschlagen kann, wenn seine Integration bricht und es herausfinden will, warum. Die
Seite muss nicht poliert oder öffentlich zugänglich sein; sie muss verlinkbar sein und den
Slack-Thread überleben, der sie angekündigt hat.
Wer pflegt eigentlich die Liste der Aufrufer?
Das besitzende Team, und das muss als echtes Artefakt behandelt werden, nicht als Wissen im Kopf der Leute. Die günstigste Version ist eine Datei im eigenen Repository der API, eine kurze Liste konsumierender Services mit einer Verantwortlichen pro Eintrag, aktualisiert, wann immer eine neue Integration gebaut wird, dieselbe Disziplin wie bei jeder Abhängigkeitserklärung. Die Alternative, vor jedem Breaking Change herumzufragen, funktioniert, bis einmal jemand vergisst, die richtige Person zu fragen, und eine still brechende interne API ist für ein Team ein kleinerer Vorfall als eine öffentliche, aber es bleibt ein Vorfall, meist entdeckt vom eigenen Bereitschaftsdienst dieses Teams statt vom API-Besitzer.
# consumers.yml
- service: billing-service
owner: "#team-billing"
since: 2026-03-01
- service: reporting-pipeline
owner: "#team-analytics"
since: 2026-06-14Eine solche Datei macht aus “wen müssen wir informieren” eine Nachschau statt eine Frage. Tools, die genau für dieses Problem gebaut wurden, wie Backstages Service-Katalog, modellieren APIs aus demselben Grund als eigenständige Entitäten mit deklarierten Konsumenten: Sobald eine Organisation genug interne Services hat, bleibt niemandes Erinnerung daran, wer was aufruft, von selbst korrekt, und irgendetwas muss stattdessen den Datensatz führen. Die Docs für das Tool, das intern ohnehin schon läuft, sind meist die richtige Stelle, um nachzuschauen, bevor man ein eigenes baut.
Was gehört in einen internen Changelog-Eintrag, das ein öffentlicher nicht braucht?
Mehr operative Konkretheit, weil die Leserin eine andere Ingenieurin ist, die innerhalb derselben Infrastruktur danach handelt, statt es als Zusammenfassung zu lesen. In welchen Umgebungen die Änderung live ist und wann, weil interne Services oft durch Stufen befördert werden, die eine öffentliche Aufruferin nie sieht. Ob die Änderung ein Konfigurations- oder Client-Bibliotheks-Update auf Seiten der Konsumentin erfordert, als Befehl formuliert, falls es einen gibt. Und, weil interne Aufrufer die Behebung oft direkt mit dem besitzenden Team abstimmen können, eine namentlich genannte Kontaktperson statt eines Support-Kanals: “ping @maria, falls das etwas kaputt macht” ist in einem internen Eintrag eine völlig vernünftige Zeile und in einem öffentlichen API-Changelog eine merkwürdige.
Gilt das genauso für ein Changelog innerhalb eines Monorepos?
Es verschärft dasselbe Problem, statt es zu ersetzen. Monorepo-Changelogs behandelt, wann ein Paket sein eigenes Changelog braucht; eine interne API, die eines von mehreren Paketen in einem Monorepo ist, braucht ihre Konsumenten trotzdem explizit erfasst, weil dieselbe Repository zu teilen mit ihren Aufrufern nicht bedeutet, dass diese eine Änderung bemerken, wenn nichts sie darauf hinweist. Nähe im Repo ist nicht dasselbe wie Nähe in der Aufmerksamkeit.
FAQ
Braucht eine rein interne API ein Changelog, wenn sie nur einen Aufrufer hat? Kaum, und eine direkte Nachricht an dieses eine Team reicht meist. Das Changelog lohnt sich, sobald es mehr als einen Aufrufer gibt, oder sobald die Aufruferliste das besitzende Team schon einmal überrascht hat, denn das ist das Zeichen, dass Erinnerung allein nicht mehr zuverlässig ist.
Sollten interne API-Änderungen denselben Review durchlaufen wie öffentliche? Die Formulierung darf leichter sein, weil die Leserin eine Kollegin statt eine externe Aufruferin ist, aber die Entscheidung, ob eine Änderung breaking ist, verdient in beiden Fällen dieselbe Sorgfalt. Eine interne Aufruferin hat trotzdem Produktionscode, der vom alten Verhalten abhängt.
Wie findet man heraus, wer eine interne API aufruft, wenn das nie erfasst wurde? Serverlogs oder die Traffic-Daten eines Service-Mesh sind die ehrliche Antwort, wenn nie ein Konsumentenverzeichnis geführt wurde; behandle diese Entdeckung als den Moment, eines anzufangen, nicht als einmalige Aufräumaktion.
Reicht eine Slack-Nachricht, oder braucht eine interne Änderung trotzdem einen formellen Changelog-Eintrag? Beides, bei allem, was nicht rein additiv ist. Die Nachricht ist das, was rechtzeitig gelesen wird; der Eintrag ist das, was ein Team, das Wochen später ein Problem sucht und die Nachricht nie sah, trotzdem finden kann.
Die technischen Aussagen in diesem Artikel wurden nicht unabhängig geprüft. Wenn etwas nicht stimmt, sagen Sie es uns, und wir korrigieren es.