APIs und Integrationsarchitekturen

APIs und Integrationsarchitekturen

0:00 Eine Schnittstelle hat eine Eigenschaft, die sie von fast allem anderen in Ihrem System unterscheidet: Sie gehört Ihnen nicht allein. Sobald jemand sie benutzt, ist sie ein Versprechen an Menschen, die Sie nicht kennen und nicht erreichen können. Genau deshalb steht bei Schnittstellen der Vertrag am Anfang und nicht am Ende.

0:17 In diesem Modul geht es um synchrone Schnittstellen, um das, was ein Gateway leisten soll, um ereignisgetriebene Integration — und um die Frage, wann welcher Stil trägt.

APIs und Integrationsarchitekturen

0:27 Vier Kapitel. Zuerst die synchronen Schnittstellen: REST als Architekturstil, Contract-first, und die Abgrenzung zu GraphQL und gRPC. Dann API-Management — mit besonderem Blick darauf, was ins Gateway gehört und was dort nichts verloren hat. Danach die asynchrone Seite: Ereignisse, Zustellgarantien und der Kommunikationsvertrag dafür. Und am Ende eine Übung an einer der vier Integrationen von Kartenwerk.

Synchrone Schnittstellen

0:55 Beginnen wir bei dem, was die meisten von Ihnen täglich bauen. REST ist so allgegenwärtig, dass man selten fragt, was der Begriff eigentlich beansprucht — und wie viel davon in typischen Schnittstellen tatsächlich steckt. Wichtig ist der erste Halbsatz: REST ist ein Architekturstil, kein Protokoll. Es gibt keine REST-Bibliothek, die Ihnen REST macht.

1:15 Der Stil beschreibt Einschränkungen — Ressourcen mit eigenen Adressen, Zugriff über die Methoden und Statuscodes von HTTP, ein zustandsloser Server. Und wie bei jedem Stil gilt, was wir in Modul acht wieder hören werden: Wer die Einschränkungen nicht einhält, bekommt die Eigenschaften nicht. Die Semantik dazu steht übrigens nicht in einem REST-Dokument, sondern in der HTTP-Spezifikation selbst.

1:40 Dieses Modell ist vor allem als Diagnosewerkzeug nützlich. Stufe null ist der einzelne Endpunkt, über den alles läuft — jeder kennt so eine Schnittstelle. Stufe eins bringt Ressourcen, Stufe zwei die Verben und Statuscodes, wie sie gemeint sind. Und dann Stufe drei, bei der Antworten Links auf mögliche nächste Schritte tragen.

1:59 Was ich Ihnen mitgeben möchte, steht in der Fußzeile: Die meisten Schnittstellen stehen auf Stufe zwei, und das ist völlig in Ordnung — solange Sie es wissen und bewusst dort bleiben. Unbewusst auf Stufe eins zu stehen ist das Problem. Hier steckt eine Begründung, die ich für eine der besten in der ganzen API-Literatur halte.

2:18 Die OpenAPI-Dokumentation empfiehlt Contract-first — und zwar mit dem Argument, dass sich in Code weit mehr Schnittstellen bauen lassen, als sich in OpenAPI beschreiben lassen. Lesen Sie das zweimal. Wer zuerst implementiert, entwirft mit hoher Wahrscheinlichkeit etwas, das sich nachher nicht sauber beschreiben lässt. Und dann erzeugt man die Beschreibung aus dem Code und bekommt ein Dokument, das formal korrekt und trotzdem unbrauchbar ist.

2:45 Fünf Schritte, die zusammen eine Haltung beschreiben: Die Beschreibung ist Quellcode. Deshalb Schritt zwei — sie gehört in die Versionsverwaltung, von Anfang an, als eine der ersten Dateien des Projekts. Schritt vier macht daraus eine wirksame Regel: Die Prüfung läuft im Bauprozess, nicht im Review, denn was Menschen prüfen sollen, wird irgendwann durchgewinkt.

3:06 Und die Fußzeile nennt das Prinzip dahinter: eine Information an genau einer Stelle. Doppelt gepflegte Wahrheiten laufen auseinander — das ist keine Prognose, sondern Erfahrung. Die Gegenüberstellung soll keine Rangfolge sein, sondern zeigen, was man jeweils eintauscht. GraphQL löst ein echtes Problem — viele Oberflächen mit sehr unterschiedlichem Datenbedarf — und macht dafür das Zwischenspeichern am Rand schwierig, weil die übliche Zuordnung über die Adresse wegfällt.

3:35 gRPC ist stark, wenn Dienste untereinander sprechen und Sie einen strengen Vertrag wollen. Beachten Sie die Fußzeile: GraphQL schweigt bewusst zu Netzverhalten, Autorisierung und Blättern. Das ist keine Lücke, sondern Absicht — nur muss es dann jemand anders lösen, nämlich Sie. Diese vier Punkte sind das, was zwischen einer funktionierenden und einer belastbaren Schnittstelle liegt.

3:57 Versionierung zuerst: Wenn Sie nicht festlegen, was als verträgliche Änderung gilt, entscheidet das der Zufall — und Ihre Aufrufer merken es als Ausfall. Blättern und Filtern sollten über alle Ressourcen gleich aussehen, sonst muss jeder Aufrufer es fünfmal lernen. Und Idempotenz ist der Punkt, an dem Kartenwerk konkret wird: Wenn eine Buchung wiederholt wird, weil die Antwort verloren ging, darf nicht zweimal verkauft werden.

4:22 Der erste Punkt ist die direkte Folge davon, Contract-first nicht ernst zu nehmen. Der zweite ist der unterschätzte: Interne und externe Schnittstellen bekommen dieselben Zusagen. Intern können Sie mit den drei Teams reden, die Ihre Schnittstelle nutzen, und gemeinsam umstellen. Extern können Sie das nicht — dort ist jede Änderung ein Ereignis.

4:42 Diese beiden Welten mit derselben Strenge zu behandeln, macht die eine zu langsam und die andere zu riskant.

API-Management

4:49 Damit zu dem, was zwischen Aufrufer und Dienst steht. Ein Gateway ist schnell eingeführt und wird erstaunlich oft zu dem Ort, an dem alles landet, was anderswo nicht passt. Achten Sie auf die Abgrenzung im zweiten Satz, sie wird oft übersehen. Ein Gateway ist der gemeinsame Eingang für alle Aufrufer und kümmert sich um Querschnittsthemen.

5:09 Ein Backend for Frontend ist etwas ganz anderes: Es schneidet Antworten auf genau eine Oberfläche zu und gehört dem Team dieser Oberfläche. Wer beides in einem Bauteil vermischt, bekommt ein Gateway, das je Aufrufer Sonderfälle kennt — und damit bei jeder Frontend-Änderung angefasst werden muss. Vier Stationen, und die dritte ist die wichtigste. Zwischen Gateway und Dienst liegt die Prüfung — Identität, Rechte, Aufrufbegrenzung.

5:34 Genau an dieser Stelle sitzt die Vertrauensgrenze, über die wir in Modul zehn ausführlich sprechen. Wichtig ist, dass diese Kette nicht als Erlaubnis missverstanden wird, im Dienst selbst nichts mehr zu prüfen. Das Gateway prüft, ob jemand hereindarf. Ob dieser Jemand genau dieses Ticket stornieren darf, weiß nur der Dienst.

5:55 Die linke Spalte hat ein gemeinsames Merkmal: Nichts davon braucht fachliches Wissen. Deshalb kann es zentral stehen. Die rechte Spalte braucht genau das — und deshalb gehört sie in die Dienste. Die Fußzeile nennt die Folge, wenn man diese Linie überschreitet: Jede Fachlogik im Gateway wird zur zweiten Wahrheit und zum Engpass, weil das Gateway meist einem anderen Team gehört.

6:16 Dann wartet eine Änderung an der Buchungslogik auf einen Termin bei der Plattformmannschaft. Diese vier Fragen sind allesamt organisatorisch, und genau deshalb bleiben sie liegen. Wer darf veröffentlichen, wer prüft vorher, wie erreichen wir die Aufrufer, wann schalten wir wirklich ab. Besonders die letzte ist heikel: Alte Versionen werden selten abgeschaltet, weil niemand weiß, wer sie noch benutzt — und so sammeln sich Schnittstellen an, die gepflegt werden müssen.

6:43 Ein Entwicklerportal ist die Antwort auf diese Fragen, aber es beantwortet sie nicht von selbst. Es macht nur sichtbar, was entschieden wurde. Der erste Punkt ist die typische Entwicklung: Das Gateway beginnt als Eingang und wird zur Sammelstelle. Der zweite betrifft Kartenwerk unmittelbar — eine Aufrufbegrenzung ist gesetzt, aber niemand kennt das erwartete Lastprofil.

7:05 Beim Vorverkaufsstart wird die Begrenzung dann zur Ursache des Ausfalls, den sie verhindern sollte. Und der letzte Punkt: Eine Schnittstelle abzukündigen, ohne die Aufrufer zu kennen, ist keine Abkündigung. Es ist eine Ankündigung, die niemand hört.

Asynchrone Integration

7:21 Wechseln wir die Betriebsart. Bisher hat jemand gefragt und auf eine Antwort gewartet. Jetzt geht es um Kommunikation, bei der niemand wartet — mit allen Vorteilen und mit einem Preis, der gern übersehen wird. Die Entkopplung hat zwei Dimensionen, und beide sind wichtig: in der Zeit und im Wissen. Der Sender wartet nicht, und er kennt seine Empfänger nicht einmal.

7:43 Das ist ein enormer Gewinn an Beweglichkeit — neue Empfänger kommen hinzu, ohne dass der Sender es merkt. Der zweite Satz enthält die Unterscheidung, an der viele Entwürfe hängen: Ein Ereignis berichtet über Vergangenes, ein Befehl verlangt etwas für die Zukunft. Wer einen Befehl als Ereignis tarnt, koppelt weiterhin — nur unsichtbar.

8:03 Die Unterscheidung zwischen den unteren beiden Zeilen ist die praktisch folgenreichste. Eine Warteschlange: eine Nachricht, ein Verarbeiter, danach ist sie weg. Ein Ereignisstrom: eine Nachricht, viele Leser, jeder mit eigener Leseposition, und die Nachricht bleibt liegen. Das ist kein Detail der Konfiguration, sondern eine Entwurfsentscheidung — im zweiten Fall können Sie später einen weiteren Leser hinzufügen, der die Vergangenheit noch einmal liest.

8:30 Die Fußzeile nennt die andere Achse: Trägt das Ereignis nur den Anlass oder den Zustand gleich mit? So wie OpenAPI den synchronen Vertrag beschreibt, beschreibt AsyncAPI den asynchronen. Eine Eigenheit sollten Sie kennen, weil sie beim ersten Lesen verwirrt: Das Dokument wird aus der Sicht einer Anwendung geschrieben. Steht dort eine Operation mit der Aktion senden, dann sendet diese Anwendung. Bei OpenAPI denkt man in Client und Server, hier in der Rolle des Beschriebenen.

8:59 Wer das verwechselt, liest den Vertrag genau verkehrt herum — und das passiert erstaunlich häufig. Hier steht der Preis der Entkopplung, und er wird konsequent unterschätzt. Der Regelfall ist mindestens einmal — also wird jede Nachricht gelegentlich doppelt ankommen. Das ist keine Störung, sondern der Normalbetrieb, und Ihr Empfänger muss damit umgehen können.

9:21 Bei Kartenwerk heißt das: Ein doppelt zugestelltes Buchungsereignis darf keinen zweiten Sitzplatz reservieren. Reihenfolge gilt meist nur innerhalb einer Partition. Und eine Dead Letter Queue ohne jemanden, der sie liest, ist schlicht ein Papierkorb mit gutem Namen. Der erste Punkt ist die direkte Folge davon, den vorigen zu ignorieren, und er ist der häufigste Fehler überhaupt in ereignisgetriebenen Systemen.

9:45 Der zweite ist subtiler: Ein Ereignis, das den halben Datensatz mitträgt, sieht nach Entkopplung aus und ist in Wahrheit eine verdeckte Kopplung an ein fremdes Datenmodell. Und der letzte Punkt ist der, der nicht technisch ist: Eventual Consistency muss der Fachseite erklärt werden, bevor sie im Betrieb darüber stolpert.

10:03 Sonst heißt es später, das System zeige falsche Zahlen.

Praxisübung

10:07 Jetzt wenden wir das an. Kartenwerk hat vier Integrationen, die unterschiedlicher kaum sein könnten — und wir suchen uns die aus, bei der die Entscheidung am meisten wehtut. Schauen Sie sich die vier an. Die Suche muss schnell antworten und darf veraltete Daten zeigen. Die Buchung muss sofort entscheiden und darf nichts doppelt verkaufen.

10:27 Die Abrechnung mit dem Zahlungsdienstleister darf nichts verlieren, muss aber nicht in Millisekunden fertig sein. Und die Einlassmeldung kommt in Stößen aus einem Netz, das an einem Veranstaltungsort selten gut ist. Vier Integrationen, vier völlig verschiedene Antworten — obwohl es dasselbe System ist. Der zweite Teil der Aufgabe ist der wichtigere: Skizzieren Sie den Vertrag. Bei einer synchronen Wahl also Endpunkt, Methode, Statuscodes und die Form der Fehlerantwort.

10:55 Bei einer asynchronen Kanal, Nachricht, Aktion und Schema. Diese Skizze bringt Lücken ans Licht, die in der Diskussion unsichtbar bleiben — vor allem bei den Fehlerfällen. Und der Hinweis stimmt: Die Abrechnung ist der interessanteste Fall, weil dort Zuverlässigkeit und Antwortzeit auseinanderfallen. Der dritte Punkt ist der, der in Übungen regelmäßig fehlt.

11:17 Wenn Sie asynchron entscheiden, ändert sich die Oberfläche: Der Nutzer bekommt keine fertige Antwort, sondern eine Zusage. Was sieht er dann — einen Zwischenstand, eine Benachrichtigung, eine Seite, die sich aktualisiert? Diese Frage gehört zur Integrationsentscheidung, nicht ins Frontend-Ticket danach. Im nächsten Modul geht es um das, worüber wir hier ständig gestolpert sind: Daten, Konsistenz und die Frage, wem was gehört.