API-Dokumentation
Die API-Dokumentation ist die Bedienungsanleitung für eine Programmierschnittstelle: Sie beschreibt, welche Anfragen ein Programm an einen fremden Dienst schicken darf und welche Antworten es dafür bekommt. Ohne sie müsste jeder Entwickler durch Ausprobieren herausfinden, wie ein Dienst funktioniert.
Programme müssen oft mit fremden Programmen zusammenarbeiten. Eine Wetter-App holt sich zum Beispiel die Vorhersage von einem Wetterdienst. Damit das klappt, gibt es an dem fremden Dienst eine feste Anschlussstelle: eine Programmierschnittstelle, kurz API. Dort ist genau festgelegt, welche Anfragen erlaubt sind und was zurückkommt. Die API-Dokumentation ist der Text, der all das beschreibt. Sie ist damit die Bedienungsanleitung für Entwickler, die den Dienst benutzen wollen — vergleichbar mit einer Speisekarte, die auflistet, was man bestellen kann und was man dafür bekommt.
Warum schlechte Docs Geld kosten
Eine Schnittstelle kann technisch perfekt sein und trotzdem niemand benutzt sie. Wenn nicht beschrieben ist, wie man sie anspricht, bleibt sie unbrauchbar. Entwickler entscheiden erfahrungsgemäß in wenigen Minuten, ob sie einen Dienst ausprobieren oder zur Konkurrenz gehen. Diese Minuten verbringen sie in der Dokumentation, nicht im Verkaufsgespräch.
Für Firmen ist das deshalb ein wirtschaftliches Thema. Zahlungsdienstleister wie Stripe oder Cloud-Anbieter verkaufen ihre Leistung fast ausschließlich über Schnittstellen. Ihre Dokumentation ist die eigentliche Produktoberfläche. Fehlt eine Information, landen die Fragen im Support, und jeder Anruf kostet Arbeitszeit.
Ein zweiter Punkt ist Verlässlichkeit. Die Dokumentation ist auch ein Versprechen: Was dort steht, soll morgen noch gelten. Ändert ein Anbieter seine Schnittstelle ohne Ankündigung, gehen bei allen Kunden gleichzeitig Programme kaputt. Gute Anbieter dokumentieren deshalb auch, was sich wann geändert hat.
Was in einer guten API-Doku drinsteht
Den Kern bildet die Referenz. Sie listet jede einzelne Funktion auf, die man aufrufen kann. Zu jeder Funktion gehören die Angaben, die man mitschicken muss, und die Beschreibung dessen, was zurückkommt. Dazu kommt die Liste der Fehlermeldungen, denn ein Programm muss auch mit Absagen umgehen können.
Reine Referenzlisten reichen aber nicht. Deshalb gibt es meist ein Einstiegskapitel, das Schritt für Schritt zum ersten funktionierenden Aufruf führt. Wichtig ist außerdem die Anmeldung: Fast jede Schnittstelle verlangt einen persönlichen Zugangsschlüssel, damit der Anbieter weiß, wer anfragt und wem er die Nutzung berechnet. Auch Grenzwerte gehören hinein, etwa die maximal erlaubte Zahl von Anfragen pro Minute.
Vieles davon entsteht heute halb automatisch. Entwickler beschreiben ihre Schnittstelle in einer standardisierten Datei, oft nach dem Format OpenAPI. Aus dieser Beschreibung erzeugt ein Werkzeug dann die Referenzseiten samt Beispielcode. Der Vorteil: Ändert sich die Schnittstelle, ändert sich die Dokumentation mit. Erklärende Texte und Beispiele muss trotzdem ein Mensch schreiben.
Von der Bastelei bis zum ChatGPT-Plugin
Man begegnet API-Dokumentationen überall, wo Dienste kombiniert werden. Wer ein Schulprojekt mit Fahrplandaten der Bahn baut, liest deren Doku. Wer einen Discord-Bot programmiert, ebenso. Die Seiten heißen dann oft schlicht « Docs » oder « Developers » und sind über die Fußzeile einer Website erreichbar.
In der KI-Branche hat das Thema zusätzlich Gewicht bekommen. Anbieter wie OpenAI oder Anthropic verkaufen Zugriff auf ihre Sprachmodelle ausschließlich über Schnittstellen. Wie viel eine Anfrage kostet, wie lang der Text sein darf, welche Einstellungen es gibt — das alles steht in der Dokumentation. Wenn in News von einem neuen Modell die Rede ist, sind die technischen Details oft dort zuerst zu finden.
Neu ist, dass inzwischen auch Programme selbst diese Texte lesen. KI-Assistenten bekommen Schnittstellenbeschreibungen vorgesetzt, um daraus Programmcode zu schreiben oder Dienste eigenständig aufzurufen. Eine saubere, maschinenlesbare Dokumentation ist damit doppelt wertvoll. Ein verbreiteter Irrtum ist übrigens, API-Dokumentation mit Nutzerhandbüchern zu verwechseln: Handbücher richten sich an Menschen vor einer Oberfläche, API-Dokumentation an Menschen, die Code schreiben.
