Mit dem Vertrag beginnen

REST-API-Dokumentation hat zwei Zielgruppen: Maschinen und Menschen. Der Vertrag beschreibt Pfade, Methoden, Parameter, Schemas und Responses; die menschliche Ebene erklärt Absicht, Grenzen und Abläufe.

Der Happy Path muss ausführbar sein

Authentifizierung, vollständigen Request und vollständige Response zeigen, damit der erste erfolgreiche Aufruf schnell gelingt. Beispiele müssen gültig und realistisch sein.

Fehler gehören zur Schnittstelle

Nicht bei 200 aufhören. Authentifizierungsfehler, Validierung, Konflikte, Limits und asynchrone Zustände dokumentieren und den nächsten Schritt erklären.

Reference und Guides trennen

Reference beantwortet „Was gibt es?“, Guides „Wie erreiche ich ein Ziel?“. Ebenen verlinken statt alles in eine Endpoint-Seite zu pressen.

Beispiele ausführbar halten

JSON, Schemas und typische Requests möglichst in CI validieren.

OpenAPI ist Quelle, nicht die ganze Experience

OpenAPI für Reference und Validierung nutzen, aber Konzepte, Authentifizierung, Limits und End-to-End-Szenarien ergänzen.

Praxisbeispiel

Mach aus „REST API richtig dokumentieren“ eine vollständige Entwickleraufgabe. Verwende eine fiktive, aber realistische Ressource wie Bericht, Gerät oder Bestellung und beschreibe den kürzesten Weg von der Authentifizierung zum erfolgreichen Ergebnis. Zeige Request, wichtige Response-Felder, einen wahrscheinlichen Fehler und die nächste Aktion danach.

Prüfe das Beispiel wie beim Bau eines Clients:

  • welche Werte ersetzt werden müssen;
  • welche IDs der Server zurückgibt und später wiederverwendet werden;
  • welcher Status oder welches Feld Erfolg bestätigt;
  • was bei falschen Credentials, Eingaben oder Limits zu tun ist.

API-Dokumentation ist stark, wenn Entwickler die Interaktion vorhersagen können und nicht nur Endpoint-Namen wiedererkennen.

Kurzer Redaktionscheck

  • Mit dem Vertrag beginnen. REST-API-Dokumentation hat zwei Zielgruppen: Maschinen und Menschen.
  • Der Happy Path muss ausführbar sein. Authentifizierung, vollständigen Request und vollständige Response zeigen, damit der erste erfolgreiche Aufruf schnell gelingt.
  • Fehler gehören zur Schnittstelle. Nicht bei 200 aufhören.
  • Reference und Guides trennen. Reference beantwortet „Was gibt es?“, Guides „Wie erreiche ich ein Ziel?“.

Verwandte Artikel