OpenAPI

Programme tauschen ständig Daten über das Internet aus. Eine Wetter-App holt sich zum Beispiel die Vorhersage von einem fremden Server. Damit das klappt, muss der Server irgendwo genau beschreiben, welche Anfragen er versteht und was er zurückschickt. Genau dafür gibt es OpenAPI: ein einheitliches Format, in dem eine solche Beschreibung aufgeschrieben wird. Die Datei ist so aufgebaut, dass sowohl Menschen sie lesen als auch Programme sie automatisch auswerten können. Man kann sie sich als eine sehr genaue Speisekarte vorstellen: Sie listet auf, was bestellbar ist, welche Angaben man dazu machen muss und was danach auf dem Teller liegt.

Warum eine Speisekarte für Server so viel Arbeit spart

Vor solchen Standards beschrieben Firmen ihre Schnittstellen in normalen Textdokumenten. Diese Texte veralteten schnell, weil niemand sie mitpflegte. Entwickler mussten dann raten oder ausprobieren, was ein Server erwartet. Das kostete Tage und führte zu Fehlern, die erst im laufenden Betrieb auffielen.

Eine OpenAPI-Datei ist dagegen maschinenlesbar. Aus ihr lassen sich automatisch eine Doku-Webseite, Testwerkzeuge und sogar fertiger Programmcode erzeugen. Ändert sich die Schnittstelle, ändert man die Datei einmal, und alles andere wird neu generiert. Das reduziert Missverständnisse zwischen Teams, die an verschiedenen Enden derselben Verbindung arbeiten.

Wichtig ist die Abgrenzung: OpenAPI ist kein Programm und keine Software. Es ist nur ein vereinbartes Format für Beschreibungen. Die eigentliche Arbeit machen weiterhin der Server und die Werkzeuge, die die Datei lesen.

Was in so einer Beschreibungsdatei steht

Eine OpenAPI-Datei ist in YAML oder JSON geschrieben. Das sind zwei einfache Textformate, in denen Informationen als Listen und Paare aus Bezeichnung und Wert stehen. Beides sieht ungefähr aus wie eine sehr ordentlich eingerückte Stichpunktliste. Der Vorteil: Ein Programm kann diese Struktur zuverlässig zerlegen, ohne Sätze verstehen zu müssen.

Den Kern bilden die sogenannten Pfade. Ein Pfad ist eine Adresse auf dem Server, etwa „/wetter/heute“. Zu jedem Pfad steht dabei, welche Aktionen erlaubt sind: Daten abfragen, neue Daten anlegen, vorhandene löschen. Dazu kommen die Parameter, also die Angaben, die der Aufrufer mitschicken muss, zum Beispiel eine Postleitzahl.

Außerdem beschreibt die Datei die Antworten. Sie legt fest, welche Felder zurückkommen und ob darin Zahlen, Text oder Wahrheitswerte stehen. Auch Fehlerfälle sind aufgeführt, etwa „Ort nicht gefunden“. Ein weiterer Abschnitt regelt die Anmeldung, also ob man einen Zugangsschlüssel braucht. Zusammen ergibt das eine vollständige Bedienungsanleitung ohne Fließtext.

Von der Entwickler-Doku zum Werkzeug für Sprachmodelle

Wer die Doku eines größeren Online-Dienstes aufruft, landet häufig auf einer Seite, die aus einer OpenAPI-Datei erzeugt wurde. Erkennbar ist sie an ausklappbaren Listen von Adressen und einem Knopf zum direkten Ausprobieren. Diese Darstellung stammt oft von einem Werkzeug namens Swagger UI. Swagger war übrigens der frühere Name des Formats, bevor es 2015 an eine offene Organisation übergeben und in OpenAPI umbenannt wurde.

In den letzten Jahren ist ein neuer Einsatzzweck dazugekommen. Damit ein Chatbot etwas anderes tun kann als Text schreiben, muss er fremde Dienste aufrufen können. Man gibt dem Modell dafür eine OpenAPI-Beschreibung, und es liest daraus ab, welche Funktionen es nutzen darf. So kann eine KI selbstständig einen Flug suchen oder einen Kalendereintrag anlegen.

Ein verbreiteter Irrtum ist, dass eine OpenAPI-Datei garantiert, dass der Server sich auch so verhält. Das tut sie nicht. Die Beschreibung kann veraltet oder schlicht falsch sein, wenn niemand sie pflegt. Deshalb prüfen viele Firmen automatisch, ob Beschreibung und echtes Verhalten noch zusammenpassen.