REST-APIs dokumentieren nach dem OpenAPI-Standard

Damit andere bequem mit einem API arbeiten können, braucht es eine gute Dokumentation. Den Standard OpenAPI können Maschinen und Menschen lesen.

Lesezeit: 6 Min.
In Pocket speichern
vorlesen Druckansicht Kommentare lesen 1 Beitrag

(Bild: Thorsten Hübner)

Von
Inhaltsverzeichnis

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. Die 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.

Immer mehr Wissen. Das digitale Abo für IT und Technik.

  • Zugriff auf alle Inhalte von heise+
  • exklusive Tests, Ratgeber & Hintergründe: unabhängig, kritisch fundiert
  • c't, iX, Technology Review, Mac & i, Make, c't Fotografie direkt im Browser lesen
  • einmal anmelden – auf allen Geräten lesen - monatlich kündbar
  • erster Monat gratis, danach monatlich 9,95 €
  • Wöchentlicher Newsletter mit persönlichen Leseempfehlungen des Chefredakteurs
GRATIS-Monat beginnen Jetzt GRATIS-Monat beginnen Mehr Informationen zu heise+