Schnittstellen-Erklärer
REST-APIs dokumentieren nach OpenAPI-Standard
Ein API stellt Entwicklern Daten zur Verfügung und nimmt Daten entgegen. Damit andere etwas damit anfangen können, braucht es eine gut lesbare Dokumentation, sonst wird das Entwickeln zum Stochern im Nebel. Mit OpenAPI gibt es einen Standard für API-Dokumentationen, die Maschinen und Menschen lesen können.
Programmierschnittstellen nach dem REST-Schema (Representational State Transfer), die per HTTP(S) bereitgestellt werden, machen Entwicklern das Leben leicht. Schnell bekommt man zum Beispiel Wetterdaten, Verkehrsinformationen oder Börsendaten für die eigene Anwendung. Die strukturierten Daten sind leicht zu verarbeiten, wenn man denn ihre Struktur kennt. Damit die Entwicklung zügig vorangeht, braucht man eine Dokumentation, aus der hervorgeht, wie die Endpunkte heißen und welche Daten es dort zu holen gibt.
Ohne Erklärung weiß schließlich kein Entwickler, ob der Endpunkt für das Wetter-API /weather oder /data heißt oder welche Parameter die Abfrage des Endpunkts erwartet. Als Betreiber eines APIs könnte man die Dokumentation als Fließtext in einer Readme-Datei zusammentragen und allen Nutzern zukommen lassen. Diese müssten sich dann aber immer noch durch viel Text arbeiten. Sinnvoller ist es, das Format der strukturierten Daten selbst in eine strukturierte Schnittstellendefinition zu verpacken. Hält man sich dann noch an einen Standard, kann man davon ausgehen, dass andere Entwickler schnell mit dem API arbeiten können.