APIs als Produkt und Vertrag verstehen

APIs als Produkt und Vertrag verstehen

0:00 Schnittstellen sind das unsichtbare Rückgrat fast jeder Anwendung, die Sie heute bauen. Die Kunden-App holt sich Daten über eine API, der Partner klinkt sich über eine API ein, und inzwischen tun das auch KI-Agenten. Technisch ist so ein Endpunkt schnell gebaut. Schwierig wird es an einer anderen Stelle: Sobald jemand anderes gegen Ihre Schnittstelle programmiert, haben Sie ein Versprechen abgegeben.

0:22 In den nächsten drei Tagen geht es genau darum — wie aus einem funktionierenden Endpunkt ein belastbarer Vertrag wird, den Sie beschreiben, testen und weiterentwickeln können, ohne fremde Systeme kaputt zu machen.

APIs als Produkt und Vertrag verstehen

0:34 Bevor wir über HTTP-Methoden oder OpenAPI reden, klären wir das Fundament. Was ist eine API überhaupt, wenn man sie nicht als Codeartefakt betrachtet, sondern als Angebot an andere? Wer sind die Beteiligten? Und woran erkennt man früh, dass ein Entwurf später teuer wird? Dieses erste Modul beantwortet die Warum-Fragen. Es liefert das Vokabular und die Denkweise, auf die alles Weitere aufbaut — und es führt unser durchgehendes Beispiel ein, die Hofkiste.

APIs als Schnittstelle und als Produkt

1:04 Fangen wir mit einer Perspektivverschiebung an. Die meisten von uns denken bei einer API zuerst an Code — Controller, Routen, Serialisierung. Für die Menschen auf der anderen Seite ist sie etwas ganz anderes: ein Angebot, auf das sie sich verlassen. Schauen wir uns an, was daraus folgt. Stellen Sie sich einen Steckdosentyp vor. Technisch ist das eine banale Sache — zwei Löcher in der Wand.

1:28 Trotzdem können Sie ihn nicht einfach ändern, denn Millionen Geräte sind darauf ausgelegt. Ihre API ist so eine Steckdose. Sie ist zugleich technische Schnittstelle und Produkt mit eigener Zielgruppe. Und der entscheidende Unterschied zu Ihrem internen Code ist die Trägheit der anderen Seite: Wer gegen Ihre Schnittstelle programmiert hat, kann seinen Code nicht in derselben Stunde ändern, in der Sie Ihren ändern.

1:52 Diese Asymmetrie ist der Grund für praktisch alles, was in diesem Seminar folgt. Die Logik hinter dieser Tabelle ist einfach: Ihre Freiheit sinkt mit der Zahl der Menschen, die Sie nicht anrufen können. Bei einer internen Schnittstelle sitzt das Consumer-Team zwei Räume weiter — eine Änderung ist eine Absprache. Bei Partnern haben Sie Verträge und Vorlaufzeiten, aber immerhin Adressen.

2:15 Bei einer öffentlichen API wissen Sie schlicht nicht, wer da draußen was aufruft; dort bleibt Ihnen nur der additive Weg. Wichtig ist: Die Reichweite ist keine technische Eigenschaft. Ein Dienst im internen Netz kann trotzdem faktisch öffentlich sein, wenn niemand mehr weiß, wer ihn nutzt. Ein Vertrag ist kein Selbstzweck und auch kein Bürokratieakt.

2:36 Er beantwortet die vier Fragen, die ein Consumer stellen muss, bevor er Code schreibt: Was gibt es, was kommt garantiert zurück, wie sieht ein Fehler aus, und wie lange gilt das alles? Interessant ist der vierte Punkt, weil er am häufigsten fehlt. Teams beschreiben ihre Endpunkte sorgfältig und schweigen zur Lebensdauer.

2:54 Dabei ist genau das die Information, die über die Architektur auf der anderen Seite entscheidet. Wer weiß, dass ein Feld nächstes Jahr verschwindet, baut anders, als wer es für ewig hält. Diese vier Fehler haben eine gemeinsame Wurzel: Die API wird von innen nach außen gedacht. Der erste ist der klassische — das Datenmodell wandert eins zu eins nach außen, und jede Schemaänderung wird zum Bruch.

3:18 Der zweite ist subtiler: Zusagen existieren, aber nur als Prosa im Wiki, wo keine Maschine sie prüfen kann. Der dritte ist eine Frage der Aufmerksamkeit; man fragt die Consumer, die man kennt, und vergisst die anderen. Und der vierte ist organisatorisch: Ohne benannte Zuständigkeit entscheidet, wer zuerst committet.

Schnittstellenstile unterscheiden

3:38 Jetzt wird es konkreter. Wenn wir HTTP verwenden — und das tun wir fast immer —, dann treffen wir damit eine Entscheidung, die weit über das Transportprotokoll hinausgeht. Sehen wir uns an, was das bedeutet und welche Stile sich unterscheiden lassen. Denn diese Wahl entscheidet mit, wie viel Arbeit Sie später selbst erledigen müssen.

3:58 RFC 9205 macht eine Unterscheidung, die im Alltag oft untergeht: Es gibt Anwendungen, die HTTP benutzen, und solche, die nur darauf aufsetzen. Der Unterschied ist keine Feinheit. Sobald Sie Port 443 und das https-Schema verwenden, laufen Ihre Nachrichten durch eine Infrastruktur, die HTTP versteht — Proxies, Caches, Gateways, Bibliotheken.

4:21 All diese Teile treffen Entscheidungen aufgrund von Methoden, Statuscodes und Headern. Wer deren Bedeutung umdeutet, kämpft ab diesem Moment gegen das eigene Ökosystem. Deshalb übernehmen Sie mit der Wahl von HTTP auch dessen Regeln. Die Gegenüberstellung zeigt, was Sie gewinnen und was Sie verschenken. Links tragen Methoden und Statuscodes Bedeutung — ein Zwischenspeicher kann eine Antwort aufbewahren, ein Monitoring-System sieht Fehlerquoten, ein Client weiß, ob er wiederholen darf.

4:51 Rechts läuft alles über einen einzigen POST-Endpunkt, und der Rumpf entscheidet. Das funktioniert, aber jede Zwischenstation ist blind, und jedes Werkzeug braucht Sonderwissen über Ihre Schnittstelle. Der Punkt ist nicht Reinheit. Der Punkt ist, dass die linke Seite Arbeit an eine Infrastruktur abgibt, die es ohnehin schon gibt.

5:11 Vier Vorgaben, die sich lohnen zu kennen. Nur registrierte Methoden und Statuscodes — das schützt Sie davor, ein eigenes Vokabular zu erfinden, das niemand versteht. Die Semantik generischer Elemente nicht umdeuten — ein 200 mit einem Fehler im Rumpf verwirrt jedes Monitoring. Einstiegspunkte über bekannte Adressen, Folgewege über Link-Relationen — so kann der Betreiber Ressourcen später verschieben.

5:34 Und der vierte Punkt ist der, den Spezifikationen am häufigsten verletzen: Feste Pfade festzuschreiben nimmt dem Betreiber die Hoheit über seinen eigenen Namensraum. Er kann Ihre Anwendung dann nicht mehr neben einer anderen betreiben. Der erste Punkt ist der Klassiker der Statuscode-Inflation: Für jeden fachlichen Fall ein eigener Code, bis niemand mehr weiß, was 418 bedeuten sollte.

5:57 RFC 9205 empfiehlt ausdrücklich das Gegenteil — großzügig die allgemeinen Codes verwenden und die Feinheit in eine sprechende Antwort legen. Wie das aussieht, sehen wir in Modul 4. Der zweite Punkt kostet spätestens beim Betrieb hinter einem Gateway Zeit. Und der dritte ist ein Kulturthema: REST ist kein Regelwerk, dessen Verletzung Sünde wäre.

6:19 Es ist ein Werkzeugkasten, aus dem man bewusst auswählt.

Entwurfswege und typische Fehlerbilder

6:23 Bleibt die Frage der Reihenfolge. Entsteht zuerst der Vertrag und dann der Code — oder umgekehrt? Diese Entscheidung wirkt sich auf alles aus, was wir am zweiten und dritten Tag machen. Schauen wir uns beide Wege an und danach die Muster, an denen APIs typischerweise scheitern. Die OpenAPI-Initiative empfiehlt Design-first, und ihre Begründung ist bemerkenswert nüchtern: In Code lassen sich weit mehr Schnittstellen bauen, als sich in OpenAPI beschreiben lassen.

6:51 Wer erst baut und dann beschreibt, stößt deshalb regelmäßig auf Konstrukte, die sich nur unvollständig oder unintuitiv abbilden lassen — und die Beschreibung wird entsprechend schlecht. Design-first dreht das um: Was nicht beschreibbar ist, entsteht gar nicht erst. Das klingt nach einer Einschränkung und ist in Wahrheit eine Qualitätssicherung, bevor die erste Zeile Code existiert.

7:13 Die vierte Zeile ist die ehrlichste. Design-first kostet Disziplin vor dem Start — jemand muss den Vertrag schreiben, während alle lieber loscoden würden. Code-first kostet Nacharbeit nach dem Start, und die fällt in kleinen Portionen an, über Monate verteilt, weshalb sie niemand summiert. Der eigentliche Unterschied steckt aber in Zeile zwei: Bei Design-first können Consumer sofort gegen einen Mock arbeiten. Sie brauchen Ihr Backend nicht.

7:39 Wie das praktisch aussieht, bauen wir in Modul 8. Alle vier Punkte lassen sich auf einen Satz zusammenziehen: Es gibt mehr als eine Wahrheit. Sobald der Vertrag an zwei Stellen lebt — als Datei und in Annotationen, oder als Datei und als Wiki-Seite —, laufen sie auseinander. Nicht dramatisch, sondern langsam, bei jeder kleinen Änderung ein Stück.

8:00 Die OpenAPI-Initiative empfiehlt deshalb ausdrücklich eine einzige Quelle der Wahrheit, abgesichert durch Prüfungen in der Pipeline. Ohne diese Prüfung merkt die Abweichung als Erster der Consumer — und zwar in Produktion. Auffällig ist, wie oft es hier nicht am Wissen scheitert, sondern an der Umsetzung. Design-first wird beschlossen, aber die Datei liegt in einem Grafikwerkzeug statt im Repository.

8:25 Ein Style Guide wird geschrieben, aber nie automatisch geprüft. Die Spezifikation gilt als Dokumentation und nicht als Quelle. Der gemeinsame Nenner: Der Vertrag wird wie ein Dokument behandelt und nicht wie Quelltext. Am zweiten Tag drehen wir genau das um — mit Versionierung, Review und Linting.

Übung

8:44 Genug Theorie für den Anfang. Wir schauen uns jetzt unser Beispielunternehmen an und wenden das Gelernte direkt darauf an. Die Hofkiste begleitet uns durch alle dreizehn Module — was Sie hier festlegen, wird uns am dritten Tag wieder einholen. Nehmen Sie sich für die Begründung Zeit, nicht für die Antwort — die Begründung ist es, die Sie später wieder brauchen werden.

9:06 Die Hofkiste liefert Gemüsekisten im Abo. Drei sehr unterschiedliche Consumer greifen auf dieselbe API zu: die eigene Kunden-App, das Portal der Logistikpartner und ein öffentlicher Verfügbarkeitsdienst. Ihre Aufgabe ist, für jeden dieser drei zu bestimmen, welche Reichweite er hat, welche Änderungen Sie sich erlauben dürfen und mit welchem Vorlauf Sie ankündigen müssen.

9:27 Es geht nicht darum, die richtige Antwort zu finden — es geht darum, die Begründung sauber zu führen. Und darum, zu merken, dass die drei sich unterscheiden müssen. Der rote Faden ist bewusst von hinten gedacht: Wir fangen nicht bei der Technik an, sondern bei der Frage, wer den Consumer baut und wie schnell er nachziehen kann.

9:46 Daraus ergibt sich die Reichweite fast von selbst, und aus der Reichweite die erlaubten Änderungsarten. Erst zum Schluss legen Sie die Fristen fest und prüfen sie an zwei konkreten Änderungswünschen gegen. Halten Sie Ihre Festlegungen fest — in Modul 13 kündigen wir einen echten Breaking Change an, und dann werden wir hier nachsehen.

10:05 Der häufigste Fehler in dieser Übung ist die pauschale Antwort: eine Frist für alle. Sie wirkt gerecht, ist aber falsch, weil ein Team, das Sie anrufen können, etwas anderes ist als ein unbekannter Aufrufer. Der zweite Fehler ist verbreiteter, als man denkt — die Reichweite wird an der Netzwerkzone festgemacht. Interne Netze sind aber voller Schnittstellen, deren Consumer niemand mehr kennt.

10:28 Und der dritte Punkt ist eine Einladung, ehrlich zu sein: Nur weil etwas im selben Cluster läuft, ist es noch lange nicht intern.