Design-first, Code-first oder Hybrid

Design-first, Code-first oder Hybrid

0:00 In Modul 1 haben wir die drei Wege kurz gestreift, jetzt gehen wir in die Tiefe. Und ich möchte gleich zu Beginn eine Erwartung dämpfen: Es geht hier nicht darum, den einen richtigen Weg zu küren. Es geht um eine viel praktischere Frage — wo liegt in Ihrem Projekt die eine Wahrheit über die Schnittstelle? Denn fast alles, was mit APIs schiefgeht, lässt sich darauf zurückführen, dass es zwei gab. Dieses Modul handelt vom Prozess drumherum: Versionierung, Review, Zuständigkeit.

Design-first, Code-first oder Hybrid

0:29 Wir klären zuerst die drei Wege und woran die Wahl im konkreten Projekt hängt. Danach wird es organisatorisch: Wie eine Vertragsänderung durch den Prozess läuft, was ein API-Review anders macht als ein Code-Review. Und zum Schluss die Frage, die in gewachsenen Organisationen die meiste Reibung erzeugt — wem gehört eigentlich der Vertrag, wenn mehrere Teams davon abhängen?

Die drei Wege gegenüberstellen

0:51 Fangen wir mit der Reihenfolge an. Entsteht zuerst der Vertrag oder zuerst der Code? Und gibt es einen dritten Weg, der beides verbindet, ohne die Nachteile beider zu erben? Und vor allem: Was ist der dritte Weg, von dem selten gesprochen wird, obwohl ihn viele Teams faktisch gehen? Er verbindet beide Richtungen und macht Abweichung technisch unmöglich.

1:13 Die Begründung der OpenAPI-Initiative für Design-first ist bemerkenswert, weil sie nicht mit Disziplin oder Prozessreife argumentiert, sondern mit einer schlichten Asymmetrie: In Code lassen sich weit mehr Schnittstellen bauen, als sich in OpenAPI beschreiben lassen. Wer zuerst baut, produziert deshalb regelmäßig Konstrukte, die sich hinterher nur unvollständig oder unintuitiv beschreiben lassen. Design-first dreht das um.

1:37 Was sich nicht beschreiben lässt, entsteht gar nicht erst. Das ist im Kern eine Qualitätssicherung, die stattfindet, bevor die erste Zeile Code existiert. Die dritte Schicht ist die, die in der Praxis am häufigsten gelebt wird und selten einen Namen bekommt. Hybrid heißt: Der Vertrag führt, aber die Implementierung erzeugt ebenfalls eine Beschreibung — und die Pipeline vergleicht beide.

2:00 Damit haben Sie den Vorteil von Design-first, nämlich die verhandelte Schnittstelle, und zusätzlich eine automatische Kontrolle, ob die Anwendung sich daran hält. Das ist mehr Aufwand als beide reinen Wege, aber es ist der einzige, bei dem Abweichung technisch unmöglich wird statt nur unerwünscht. Die erste Frage ist die praktisch wichtigste: Wie viele Consumer gibt es, und müssen sie parallel entwickeln?

2:23 Wenn ein Frontend-Team auf Ihr Backend wartet, ist Design-first fast immer die Antwort, weil es die Wartezeit eliminiert. Die vierte Frage betrifft den häufigsten Realfall, über den in Seminaren zu selten gesprochen wird: eine bestehende Anwendung nachträglich beschreiben. Dort ist Code-first der pragmatische Einstieg — Sie holen sich erst einmal ein Bild des Ist-Zustands und wechseln danach auf den hybriden Weg.

2:46 Der erste Punkt ist der Kernfehler, dem dieses ganze Modul gewidmet ist: Der Vertrag existiert doppelt. Das passiert nie mit Absicht, sondern schleichend — jemand pflegt Annotationen, weil das bequem ist, und die Datei bleibt daneben liegen. Der zweite Punkt ist die typische Schwäche von Code-first: Ohne sorgfältige Annotationen beschreibt der Generator Ihre internen Klassen, inklusive Feldern, die nach außen nichts zu suchen haben.

3:11 Und der dritte ist Design-first ohne Kontrolle — schön formuliert und unverbindlich.

Verträge versionieren und prüfen

3:16 Jetzt zum Prozess. Wenn der Vertrag Quelltext ist, dann gehört er auch behandelt wie Quelltext — mit allem, was dazugehört: Branch, Pull Request, automatische Prüfung, Review. Denn ein Vertrag, den niemand zur Prüfung vorgelegt bekommt, ist eine Absichtserklärung. Erst der Prozess drumherum macht daraus etwas, worauf sich andere verlassen können.

3:38 Die OpenAPI-Initiative formuliert das als eine ihrer Best Practices: Beschreibungen sind erstklassige Quelldateien, nicht bloße Dokumentationsartefakte. Der Unterschied ist nicht kosmetisch. Eine Datei im Repository hat eine Historie — Sie können sehen, wann ein Feld hinzukam und wer es begründet hat. Sie hat Reviews, also einen Moment, in dem jemand anderes hinschaut. Und sie hat automatische Prüfungen.

4:03 Ein Vertrag, der in einem Grafikwerkzeug liegt, hat nichts davon, egal wie schön er dort aussieht. Der entscheidende Schritt ist der zweite, und dort besonders der Vergleich zur Vorgängerfassung. Validierung sagt nur, ob das Dokument formal korrekt ist — das ist die niedrige Hürde. Linting prüft Ihre Hausregeln. Aber erst der Vergleich beantwortet die Frage, die für Ihre Consumer zählt: Bricht diese Änderung etwas?

4:30 Ohne diesen Schritt ist ein Bruch eine Frage der Aufmerksamkeit im Review, und Aufmerksamkeit ist schlecht skalierbar. Mit ihm ist er ein roter Lauf. Wie das konkret aussieht, bauen wir in Modul 13. Der Unterschied ist die Lebensdauer dessen, worüber Sie entscheiden. Eine Implementierungsentscheidung können Sie nächsten Monat revidieren; eine Zusage an einen unbekannten Consumer nicht.

4:53 Deshalb steht die Kompatibilitätsfrage im API-Review ganz vorn, noch vor Stil und Eleganz. Und der dritte Punkt ist organisatorisch wichtig: Es muss jemand dabei sein, der die anderen Consumer kennt. Das eigene Team sieht immer nur den eigenen Client. Der vierte Punkt spart auf Dauer die meiste Zeit — Entscheidungen festhalten, damit dieselbe Frage nicht in vier Wochen wieder verhandelt wird.

5:17 Der zweite Punkt beschreibt ein Review, das stattfindet und nichts prüft: Tippfehler und Formulierungen werden diskutiert, die Kompatibilitätsfrage stellt niemand. Der dritte ist die Kapitulation vor dem Zeitdruck — der Vertrag wird nach dem Release nachgezogen, damit er wieder zur Implementierung passt. Damit ist er zur Dokumentation degradiert und hat keine steuernde Kraft mehr.

5:38 Und der vierte ist ein Ablauffehler mit realen Folgen: Erzeugte Clients zu veröffentlichen, bevor der Vertrag gemerged ist, macht einen Entwurf faktisch verbindlich.

Ownership und organisationsweite Standards

5:48 Kommen wir zur unbequemen Frage. Ein Vertrag betrifft mehrere Parteien — und irgendjemand muss entscheiden dürfen, wenn sie sich uneinig sind. Denn solange niemand benannt ist, entscheidet der Zufall — und der heißt in der Praxis meistens: wer zuerst committet. Wir schauen uns Rollen, Style Guides und ihre Grenzen an. Der Satz auf der Folie ist bewusst spitz formuliert: Ohne benannte Zuständigkeit entscheidet, wer zuerst committet.

6:14 Das ist keine Polemik, sondern die Beobachtung aus vielen Projekten. Contract Ownership heißt, dass eine Stelle über den Vertrag entscheidet und für seine Verlässlichkeit einsteht. Das ist ausdrücklich nicht dasselbe wie die Zuständigkeit für die Implementierung. Das Providerteam entscheidet über Umsetzung und Zeitplan; ob eine Änderung mit den Zusagen an Dritte vereinbar ist, ist eine andere Frage — und oft eine andere Person.

6:39 Die Logik der Tabelle liegt in den beiden Spalten rechts. Es gibt einen Unterschied zwischen entscheiden und gehört werden, und ihn nicht zu machen ist die Ursache vieler zäher Abstimmungen. Consumerteams entscheiden nicht über Ihren Vertrag — aber sie müssen gehört werden, wenn ein Bruch oder eine Frist ansteht. Die Sicherheit entscheidet nicht über Ihre Ressourcen, muss aber bei neuen Endpunkten dabei sein.

7:02 Und die Fußnote ist ernst gemeint: Diese Festlegung gehört ins Repository, wo man sie im Zweifelsfall nachlesen kann. Der eigentliche Nutzen steht im ersten Punkt: Wiederkehrende Fragen einmal entscheiden statt in jedem Review. Ob Feldnamen in Kleinschreibung mit Unterstrich oder in gemischter Schreibweise stehen, ist inhaltlich egal — aber es zwanzigmal zu diskutieren ist teuer.

7:24 Der dritte Punkt macht den Unterschied zwischen einem gelebten und einem toten Style Guide: Er lässt sich als Linting-Regelwerk automatisch prüfen. Und der vierte ist die Reifeprüfung — ein guter Style Guide erlaubt begründete Abweichungen. Regelwerke ohne Ausnahmen werden umgangen. Der erste Punkt ist der häufigste: Der Style Guide steht im Wiki und wird nirgends geprüft. Damit ist er eine Meinung.

7:47 Der zweite ist das Gegenteil und mindestens so schädlich — Regeln so streng, dass jedes Team eine Ausnahme braucht. Nach der zwanzigsten Ausnahme ist das Regelwerk erledigt. Und der vierte beschreibt eine Organisationsform, die man selten offen kritisiert: Ownership bei einem Gremium, das monatlich tagt. In einem Projekt mit wöchentlichen Releases bedeutet das, dass die Entscheidung faktisch woanders fällt.

Übung

8:12 Jetzt schlüpfen Sie in die Rolle des Reviewers. Es liegt eine Änderung an der Hofkiste-Spezifikation vor, und Sie müssen entscheiden — begründet und schriftlich. Die vorgelegte Änderung ist bewusst so gewählt, dass die Antwort nicht auf der Hand liegt. Sie hängt davon ab, wo das Feld steht. Vorgelegt wird eine Änderung, die harmlos aussieht: Ein bisher optionales Feld wird zum Pflichtfeld.

8:35 Ihre Aufgabe ist zu bestimmen, ob das kompatibel ist, welche Regel Ihres Style Guides berührt wird und ob die Änderung ohne Versionswechsel raus darf. Der Reiz der Aufgabe liegt darin, dass die Antwort davon abhängt, wo das Feld steht — in der Anfrage oder in der Antwort. Genau diese Unterscheidung nehmen wir in Modul 13 systematisch auseinander.

8:56 Schritt eins ist bewusst knapp gehalten: fünf Regeln, mehr nicht. Ein Style Guide, den man in fünf Minuten schreibt, ist einer, den man auch anwendet. Schritt drei ist der Kern — für welche Consumer ist das ein Bruch? Und Schritt vier ist die Übung, die im Alltag am meisten fehlt: die Entscheidung in drei Sätzen aufschreiben.

9:15 Nicht diskutieren, aufschreiben. Denn nur was aufgeschrieben ist, kann in sechs Monaten jemand nachlesen, der die Diskussion nicht miterlebt hat. Der erste Punkt ist der verbreitetste Denkfehler in dieser Übung: Die Änderung gilt als harmlos, weil der eigene Client das Feld ohnehin setzt. Das ist genau die Perspektive, gegen die ein API-Review antritt.

9:36 Der zweite Punkt ist die technische Version davon — Kompatibilität wird nur für die Antwort geprüft, obwohl in der Anfrage die härteren Regeln gelten. Und der dritte ist die organisatorische Schwachstelle: Eine mündliche Entscheidung ist morgen nicht mehr auffindbar und wird in vier Wochen neu verhandelt.