Einheit 11 — API-Dokumentation lesen
Was du nach dieser Einheit weißt: Du kannst Swagger/OpenAPI-Dokumentation lesen, weißt welche Formen von API-Dokumentation es gibt und wie du mit unvollständiger oder veralteter Doku umgehst.
Warum API-Dokumentation oft unbefriedigend ist
Die Realität: Viele APIs sind schlecht dokumentiert. Manche Endpunkte existieren nicht in der Doku, manche Felder sind falsch beschrieben, manche Beispiele sind veraltet. Das ist normal und kein Zeichen eines schlechten Systems — Dokumentation wird häufig als nachrangig behandelt.
Strategien für den Umgang damit:
- Immer mit einem echten Test (Postman, CURL) verifizieren
- Die Community fragen (Stack Overflow, GitHub Issues des SDK)
- Beim Anbieter-Support direkt anfragen
- Mit einem Netzwerk-Sniffer (z. B. Browser DevTools) schauen was die offizielle App tatsächlich schickt
Dokumentationsformen
Swagger / OpenAPI
Der heutige Standard für maschinell lesbare API-Dokumentation. Eine JSON- oder YAML-Datei beschreibt vollständig alle Endpunkte, Parameter, Request- und Response-Strukturen.
Swagger-Dokumentation ist oft interaktiv erreichbar — du erkennst sie an der URL:
https://api.example.com/swagger
https://api.example.com/api-docs
https://api.example.com/openapi.json
Was du in einer Swagger-Doku findest:
GET /customers/{id}
Beschreibung: Gibt einen einzelnen Kunden zurück
Pfad-Parameter:
id (integer, required): ID des Kunden
Header:
Authorization (string, required): Bearer Token
Antworten:
200: Customer-Objekt
{
"id": integer,
"name": string,
"email": string,
"status": "active" | "inactive"
}
404: Kunde nicht gefunden
401: Nicht authentifiziert
Swagger UI erlaubt es, Anfragen direkt im Browser auszuführen — einmal authentifizieren, dann alle Endpunkte live ausprobieren.
Postman Collections
Viele Anbieter liefern ihre API-Dokumentation als Postman Collection — eine exportierbare Sammlung von vorkonfigurierten Anfragen.
Was eine Postman Collection enthält:
- Alle relevanten Endpunkte als fertige Requests
- Beispiel-Payloads
- Vordefinierte Umgebungsvariablen (Base URL, Token, ...)
- Manchmal: automatische Tests
Postman Collections werden oft als .json-Datei bereitgestellt oder über einen "Run in Postman"-Button direkt importiert.
Einschränkung: Postman Collections werden vom Anbieter manuell gepflegt — sie können veraltet oder unvollständig sein.
Manuelle Dokumentation (Wiki, PDF, HTML)
Viele ältere Systeme (besonders On-Prem ERP-Systeme) haben Dokumentation als PDF oder Word-Dokument. Typische Probleme:
- Nur intern verfügbar
- Versions-spezifisch — Doku für v5 gilt nicht für v6
- Unvollständig: "weitere Parameter auf Anfrage"
- Kein Datenwörterbuch für Feldwerte (was bedeutet
status: 3?)
Datenwörterbücher
Manche Systeme (SAP, Microsoft Dynamics, größere ERPs) haben ein eingebettetes Datenwörterbuch — eine Dokumentation aller Tabellen, Felder und Wertelisten die nur über das System selbst zugänglich ist.
Das bedeutet: um die API vollständig zu verstehen, brauchst du Zugang zu diesem Tool. Ohne das Tool bleibt die Bedeutung mancher Felder unklar.
Was du beim ersten Lesen einer API-Doku suchst
Schritt 1: Base URL und Versionierung
Base URL: https://api.example.com/v2
Schritt 2: Authentifizierungsverfahren
Authentication: Bearer Token
Token-Endpunkt: POST /auth/token
Schritt 3: Die relevanten Endpunkte Nicht alle lesen — nur die suchen die für deinen Use Case relevant sind.
Schritt 4: Request- und Response-Struktur Welche Felder sind Pflichtfelder? Welche Typen haben sie? Was gibt der Endpunkt zurück?
Schritt 5: Fehler-Codes Welche spezifischen Fehlercodes definiert diese API? Was bedeuten sie?