API-Evolution, Auslieferung und KI-Unterstützung

API-Evolution, Auslieferung und KI-Unterstützung

0:00 Wir sind beim letzten Modul, und es schließt den Kreis zum ersten. Damals ging es um das Versprechen, das eine API gibt. Jetzt geht es darum, wie man dieses Versprechen ändert, ohne es zu brechen — und wenn ein Bruch unvermeidlich ist, wie man ihn so ankündigt, dass niemand überrascht wird. Dazu kommt der Teil, der in Ihren Projekten gerade an Bedeutung gewinnt: Wie setzt man Coding Agents beim Entwurf von Verträgen ein, ohne die Kontrolle abzugeben?

API-Evolution, Auslieferung und KI-Unterstützung

0:26 Vier Themen zum Abschluss. Zuerst die handwerkliche Frage, welche Änderungen kompatibel sind und welche nicht — mit einer Tabelle, die Sie mitnehmen können. Dann die Abkündigung: Wie man sie standardkonform kommuniziert. Danach die Absicherung in der Pipeline. Und zum Schluss der Umgang mit KI-Unterstützung. Am Ende liefern Sie den Breaking Change der Hofkiste kontrolliert aus.

Kompatibel weiterentwickeln

0:49 Beginnen wir mit dem Handwerk. Die Frage, ob eine Änderung kompatibel ist, wird in Reviews viel diskutiert und lässt sich erstaunlich präzise beantworten — wenn man sie richtig stellt. Wir arbeiten dabei mit einer Tabelle, die Sie mitnehmen können — sie unterscheidet nach Antwort und Anfrage, und genau diese Unterscheidung ist der Schlüssel.

1:09 Die brauchbarste Definition lautet: Eine Änderung ist kompatibel, wenn bestehende Consumer sie ignorieren können. Damit ist der Test einfach — stellen Sie sich einen Consumer vor, der Ihren neuen Vertrag nie gelesen hat. Funktioniert er weiter? Ein neues optionales Feld in der Antwort kann er ignorieren. Ein neues Pflichtfeld in der Anfrage kann er nicht ignorieren, denn er schickt es nicht.

1:32 Diese Perspektive löst die meisten Diskussionen sofort, weil sie den Blickwinkel wechselt: weg von Ihrem Code, hin zum fremden. Die Struktur dieser Tabelle ist der eigentliche Lerninhalt: Dieselbe Änderung ist in der Antwort und in der Anfrage unterschiedlich zu bewerten. Ein neues Pflichtfeld ist in der Antwort harmlos und in der Anfrage ein Bruch. Ein entferntes Feld ist genau umgekehrt.

1:55 Wer sich das einmal klarmacht, beurteilt Änderungen deutlich schneller. Und die Fußnote nennt den Fall, den fast alle unterschätzen: ein zusätzlicher Aufzählungswert. Für Consumer, die alle Fälle abschließend behandeln, ist das ein Bruch — deshalb gehört er angekündigt. Interessant ist, was hier nicht steht. RFC 9205 nennt drei Mechanismen für inkompatible Änderungen — eine eigene Link-Relation, einen eigenen Medientyp, ein eigenes Header-Feld.

2:23 Alle drei haben gemeinsam, dass das Bestehende unangetastet bleibt und das Neue daneben tritt. Die Version im Pfad kommt in dieser Liste nicht vor, obwohl sie in der Praxis der verbreitetste Weg ist. Das ist kein Verbot, aber eine Einladung zum Nachdenken: Eine neue Versionslinie im Pfad verdoppelt Ihre Betriebslast, ein neuer Medientyp nicht.

2:45 Der zweite Punkt ist der teuerste im Betrieb und tritt zuverlässig ein: Zwei Versionen laufen dauerhaft parallel, weil die Abschaltung immer verschoben wird. Deshalb ist die Ankündigung, die wir gleich besprechen, kein Nice-to-have — sie ist die Voraussetzung dafür, dass Abschalten überhaupt möglich wird. Der dritte Punkt ist ein Muster, das gut gemeint ist und trotzdem schadet: Ein Feld stillschweigend umbenennen und das alte kurz mitliefern.

3:10 Kurz ist dabei nie definiert, und niemand weiß, wann es endet.

Deprecation kontrolliert kommunizieren

3:14 Weiter mit der Ankündigung. Seit RFC 9745 gibt es dafür einen Standard, und er ist erfreulich einfach — zwei Header und eine Link-Relation. Wichtig ist die Reihenfolge: erst ankündigen, dann abschalten — und dazwischen genug Zeit, dass die Consumer wirklich reagieren können. Wie lange das ist, haben Sie in Modul 1 festgelegt.

3:37 RFC 9745 standardisiert das Antwort-Header-Feld Deprecation. Sein Wert ist ein Datum im Format strukturierter Felder, und es kann in beide Richtungen zeigen: der Zeitpunkt, zu dem die Ressource veraltet ist — oder zu dem sie es sein wird. Damit können Sie eine Abkündigung vorab ankündigen, was der freundlichere Weg ist. Und der entscheidende Punkt: Diese Information reist mit jeder Antwort mit.

4:01 Sie erreicht damit auch Consumer, die Ihren Newsletter nicht lesen und Ihr Änderungsprotokoll nicht kennen. Drei Zeilen, drei Aufgaben. Deprecation nennt den Zeitpunkt der Abkündigung, Sunset den Zeitpunkt, ab dem die Ressource nicht mehr antwortet — der stammt aus dem älteren RFC 8594. Und die Link-Relation führt auf eine Seite für Menschen: den Migrationsleitfaden.

4:25 Die Fußnote nennt eine Regel, die der RFC ausdrücklich festschreibt: Der Sunset-Zeitpunkt darf nie vor dem Deprecation-Zeitpunkt liegen. Das klingt selbstverständlich und ist es in hektischen Releases nicht immer. Der dritte Punkt ist der, der über den Erfolg entscheidet: ein Migrationsleitfaden, der den Weg von alt nach neu an einem Beispiel zeigt.

4:47 Nicht das Neue beschreiben — den Übergang zeigen. Und der vierte Punkt ist eine Klarstellung aus dem RFC, die man kennen sollte: Diese Angaben sind ein Hinweis. Clients müssen auch ohne sie funktionieren, und Sie dürfen sich nicht darauf verlassen, dass jemand sie auswertet. Sie sind eine Bringschuld, keine Absicherung.

5:06 Der erste Punkt ist der Grund, warum die Header überhaupt existieren: Ein Änderungsprotokoll erreicht nur die, die es lesen. Der zweite ist eine Frage des Anstands und der Realität — zwei Wochen Vorlauf für einen Bruch bedeuten, dass irgendein Team seine Planung umwirft oder es einfach nicht schafft. Der dritte ist der operative Kern, den viele vergessen: messen, ob noch Aufrufe kommen. Ohne diese Messung ist das Abschalten ein Sprung ins Dunkle, und deshalb wird es verschoben.

Verträge in CI/CD absichern

5:34 Jetzt bringen wir das in die Pipeline. Denn alles, was wir besprochen haben, hängt an einer Frage: Merkt jemand rechtzeitig, dass eine Änderung inkompatibel ist? Denn alles Bisherige nützt wenig, wenn die Prüfung von der Aufmerksamkeit einzelner Personen abhängt. Wir bauen daraus eine Kette, die bei jedem Lauf dieselbe Frage stellt.

5:55 Der Vertragsvergleich ist die technische Antwort auf die Frage, die wir eben von Hand beantwortet haben. Er stellt die neue Fassung der alten gegenüber und meldet inkompatible Änderungen — automatisch, bei jedem Lauf, ohne dass jemand aufmerksam sein muss. Als Quality Gate macht er den Unterschied zwischen einer bemerkten und einer ausgelieferten Inkompatibilität.

6:15 Und diese beiden Fälle unterscheiden sich um mehrere Größenordnungen in den Kosten: einmal ein roter Lauf, einmal ein Vorfall bei einem Kunden. Diese Kette ist die Zusammenfassung des ganzen Seminars in fünf Kästen. Validieren prüft die Form, Linten die Hausregeln, der Diff die Kompatibilität, die Contract Tests das tatsächliche Zusammenspiel — und am Ende steht die Freigabe, die bei Pact an der Matrix hängt.

6:39 Jede Stufe beantwortet eine andere Frage, und keine ersetzt eine andere. Wenn Sie aus diesen drei Tagen ein Bild mitnehmen, dann dieses. Es lässt sich in fast jeder Pipeline schrittweise aufbauen. Vier Dinge, die keine Pipeline erledigen kann. Eine benannte Stelle für Ausnahmen — denn es wird Ausnahmen geben, und sie sollten entschieden statt erschlichen werden.

7:01 Ein Inventar aller Endpunkte, womit wir wieder bei API9 aus Modul 9 sind. Messwerte über die Nutzung abgekündigter Ressourcen, ohne die niemand abzuschalten wagt. Und eine feste Frist für öffentliche Änderungen. Der Wert einer festen Frist liegt darin, dass sie nicht jedes Mal neu verhandelt wird — weder von Ihnen noch von den Consumern.

7:22 Der erste Punkt ist der Klassiker jeder Automatisierung: Der Diff läuft, sein Ergebnis erscheint im Protokoll, und niemand liest Protokolle. Der zweite ist eine Reihenfolgefrage mit großer Wirkung — Contract Tests nach dem Deployment sind eine Diagnose, davor sind sie eine Verhinderung. Und der dritte beschreibt die Erosion, der jede Regel ausgesetzt ist: Wenn die Ausnahme jedes Mal gewährt wird, weil der Termin drängt, ist die Regel nach dem dritten Mal Dekoration.

Coding Agents kontrolliert einsetzen

7:48 Zum Schluss ein Thema, das vor zwei Jahren in diesem Seminar noch nicht vorkam. Coding Agents können beim Entwurf von Verträgen helfen — die Frage ist, an welcher Stelle und unter welcher Kontrolle. Die Antwort darauf ist weniger technisch als organisatorisch. Es geht um die Stelle, an der aus einem Vorschlag eine Zusage wird — und dort muss dieselbe Prüfung greifen wie sonst auch.

8:11 Die Unterscheidung, auf die es ankommt, ist die zwischen Vorschlag und Zusage. Ein Agent liefert einen Vorschlag — schnell, oft brauchbar, manchmal überzeugend falsch. Verbindlich wird daraus erst etwas, wenn es dieselbe Prüfung durchlaufen hat wie jede handgeschriebene Änderung: Validierung, Linting, Diff, Review. Das klingt nach einer Selbstverständlichkeit und wird trotzdem regelmäßig übersprungen, weil ein erzeugter Vertrag so vollständig aussieht.

8:37 Vollständigkeit ist aber kein Beleg für Richtigkeit — bei Verträgen sogar besonders wenig. Die vier Punkte haben etwas gemeinsam: Es geht immer um Fleißarbeit auf Basis von etwas, das bereits existiert. Beispiele zu einem vorhandenen Schema, fehlende Beschreibungen, ein Migrationsleitfaden aus einem Diff, Contract Tests für beschriebene Interaktionen.

8:58 Das ist genau die Art Arbeit, die im Alltag liegen bleibt — nicht weil sie schwer ist, sondern weil sie mühsam ist. Was hier nicht steht, ist ebenso wichtig: die Modellierungsentscheidungen aus Modul 2. Die sollten Sie selbst treffen. Der rote Faden ist: erst die Maschine, dann der Mensch. Validierung und Linting kosten Sekunden und fangen einen Teil der Probleme ab, bevor jemand Lesezeit investiert.

9:23 Der zweite Schritt ist der, den keine Maschine übernehmen kann — heißen die Ressourcen so, wie die Fachseite spricht? Ein Agent kennt Ihre Fachsprache nicht. Und die Fußnote dreht den Spieß um: Ein gepflegter Vertrag ist selbst guter Kontext für Agenten, weil er die Schnittstelle maschinenlesbar beschreibt. Wer ihn hat, bekommt bessere Vorschläge.

9:44 Der erste Punkt beschreibt den Mechanismus, um den es hier geht: Plausibilität wird mit Richtigkeit verwechselt. Der zweite ist die konkrete Folge — erfundene Felder wandern in die Dokumentation, und ab dem Moment sind sie eine Zusage, für die jemand einstehen muss. Der dritte ist ein Datenschutzthema, das mit Agenten neu auftritt: Beispiele mit echten Daten aus einem Testsystem, die der Agent als Vorlage fand.

10:08 Und der vierte ist die Ironie der Sache — die Prüfung entfällt gerade dann, wenn es schnell gehen sollte.

Übung

10:14 Und damit zur letzten Übung dieses Seminars. Sie führt zusammen, was wir in drei Tagen aufgebaut haben — und sie beginnt mit einer Änderung, die sich nicht vermeiden lässt. Sie ist bewusst die aufwendigste des Seminars, weil sie alles zusammenführt: Vertrag, Diff, Ankündigung, Contract Tests und Pipeline. Die Hofkiste ersetzt ihr flaches Adressfeld durch ein strukturiertes Adressobjekt. Das ist ein echter Bruch — kein Grenzfall.

10:40 Ihre Aufgabe ist, ihn kontrolliert auszuliefern: Der Vertragsdiff meldet ihn, die alte Ressource kündigt mit Deprecation und Sunset an, ein Migrationsleitfaden liegt vor, und die Contract Tests halten die Auslieferung auf, bis die Consumer nachgezogen sind. Damit greifen alle Werkzeuge dieses Seminars zum ersten Mal gleichzeitig ineinander.

11:00 Der zweite Schritt ist der wichtigste, und er wird gern übersprungen: Kann man es additiv lösen? Beide Felder eine Zeit lang liefern, das neue befüllen, das alte als deprecated markieren — dann ist aus dem Bruch eine geordnete Migration geworden. Die Fußnote sagt es deutlich: Dieser Weg ist fast immer der billigere, weil er den Zeitdruck von beiden Seiten nimmt.

11:21 Und Schritt fünf schließt den Kreis zu Modul 10: Der Diff und die Contract Tests werden zum Gate, nicht zum Bericht. Der erste Punkt ist die Reaktion, gegen die dieses ganze Modul geschrieben ist: Der Bruch wird gemeldet und als unvermeidlich abgehakt. In den meisten Fällen ist er das nicht. Der zweite ist die häufigste Ungerechtigkeit bei Fristen — sie richtet sich nach dem eigenen Release statt nach den Consumern.

11:46 Und der dritte schließt an Modul 1 an: Ein Leitfaden, der das neue Objekt beschreibt, aber nicht die Umstellung, hilft niemandem. Damit sind wir am Ende — und Sie haben eine API, die man weiterentwickeln kann.