Eine API ist nicht ausreichend dokumentiert, nur weil ihre Endpunkte oder Nachrichten aufgelistet sind. Nutzende müssen verstehen, welchen betrieblichen Zweck die Schnittstelle erfüllt, was die Daten bedeuten, wie sie sich im Fehlerfall verhält und wie Änderungen angekündigt werden.
Eine gute Dokumentation ist deshalb zugleich Vertrag, Gebrauchsanleitung und Betriebswissen.
Was gehört in eine API-Dokumentation?
Zweck und Verantwortung
Am Anfang stehen die Fragen, die sich nicht aus einem technischen Schema ableiten lassen:
- Welche betriebliche Leistung unterstützt die API?
- Für welche Verbraucher und Anwendungsfälle ist sie gedacht?
- Welches System ist für welche Daten führend?
- Wer verantwortet Inhalt, Betrieb und Freigabe von Änderungen?
- Wo erhalten Nutzende Unterstützung?
Diese Angaben verhindern, dass eine technisch nutzbare Schnittstelle außerhalb ihres vorgesehenen Kontextes eingesetzt wird.
Maschinenlesbarer Vertrag
Der Vertrag beschreibt die erlaubten Aufrufe oder Nachrichten, Datenstrukturen und Antworten in einer Form, die Werkzeuge verarbeiten können. Der passende Standard hängt vom Interaktionsmodell ab:
| Interaktionsmodell | Geeignete Beschreibung | Typischer Einsatz |
|---|---|---|
| HTTP-basierte API | OpenAPI Specification | Pfade, Operationen, Parameter, Antworten und Sicherheitsverfahren beschreiben |
| Ereignis- oder nachrichtenbasierte API | AsyncAPI Specification | Kanäle, Nachrichten, Produzenten, Verbraucher und Protokolle beschreiben |
| GraphQL-API | GraphQL-Schema mit Beschreibungen | Typen, Felder, Abfragen, Mutationen und deren Bedeutung dokumentieren |
Solche Standards ersetzen die fachliche Erklärung nicht. Sie schaffen aber eine eindeutige Quelle, aus der sich Referenzdokumentation, Prüfungen oder Teile einer Client-Integration erzeugen lassen.
Fachliche Semantik
Feldnamen allein erklären selten zuverlässig, was Daten bedeuten. Zu dokumentieren sind insbesondere:
- Bedeutung, Einheit und erlaubte Werte eines Feldes,
- Pflichtangaben und fachliche Abhängigkeiten,
- Identitäten und Schlüssel,
- Zeitpunkt und Gültigkeit eines Wertes,
- Umgang mit fehlenden, unbekannten oder gelöschten Daten,
- Herkunft und verantwortliches Quellsystem.
Gerade diese Ebene entscheidet, ob zwei Systeme lediglich Daten übertragen oder tatsächlich dasselbe darunter verstehen.
Verhalten und Beispiele
Nutzende brauchen realistische Beispiele für den Normalfall und wichtige Ausnahmen. Dazu gehören:
- vollständige Anfragen, Antworten oder Nachrichten,
- Authentifizierung und erforderliche Berechtigungen,
- Fehlercodes und fachlich verständliche Fehlerbeschreibungen,
- Wiederholungen, Zeitüberschreitungen und doppelte Nachrichten,
- Mengenbegrenzungen, Seitennavigation oder Größenlimits,
- Reihenfolge- und Konsistenzzusagen,
- Testzugänge oder eine sichere Testumgebung.
Beispiele sollten aus demselben Vertrag geprüft werden wie die API selbst. Von Hand gepflegte Beispiele veralten leicht.
Lebenszyklus und Betrieb
Auch eine fachlich und technisch gute API bleibt nur verlässlich, wenn ihr Betrieb geregelt ist:
- Wie werden Versionen und Änderungen gekennzeichnet?
- Welche Änderungen sind kompatibel, welche nicht?
- Wie lange werden alte Varianten unterstützt?
- Wie werden Einschränkungen und Abschaltungen angekündigt?
- Welche Verfügbarkeit und Reaktionszeiten sind zugesagt?
- Wo sind Status, Änderungsprotokoll und Ansprechpartner zu finden?
Eine überraschende Änderung kann eine Schnittstelle unbrauchbar machen, obwohl ihre Dokumentation am Tag der Einführung vollständig war.
Design-first oder Code-first?
Bei Design-first wird der Vertrag vor der Umsetzung abgestimmt. Das erleichtert die frühe Klärung zwischen Fachseite, Entwicklung und späteren Nutzenden. Bei Code-first entsteht die Beschreibung aus der Implementierung. Das kann gut funktionieren, wenn die fachliche Bedeutung zusätzlich gepflegt und die erzeugte Beschreibung regelmäßig geprüft wird.
Entscheidend ist weniger die Richtung als eine Regel: Es darf nur eine verbindliche Quelle geben, und Vertrag, Implementierung und veröffentlichte Dokumentation dürfen nicht auseinanderlaufen.
Wie bleibt die Dokumentation aktuell?
Die Pflege gehört in den Änderungsprozess der API:
- Eine Änderung beginnt mit der Anpassung des Vertrags und der fachlichen Beschreibung.
- Automatische Prüfungen kontrollieren Syntax und vereinbarte Gestaltungsregeln.
- Vertragstests prüfen, ob Anbieter und Verbraucher weiterhin zusammenpassen.
- Beispiele werden automatisiert gegen Schema oder Testsystem geprüft.
- Auswirkungen, Migration und Abschalttermine werden vor der Freigabe dokumentiert.
- Verantwortliche prüfen regelmäßig, ob Zweck, Ansprechpartner und Betriebsangaben noch stimmen.
Woran erkenne ich eine verlässliche Dokumentation?
Ein neuer Nutzer kann einen vorgesehenen Anwendungsfall umsetzen, ohne versteckte Annahmen telefonisch erfragen zu müssen. Zugleich kann der Betreiber erkennen, wer von einer Änderung betroffen ist und wie eine Migration sicher gelingt.
Die eigentliche Qualitätsfrage lautet daher nicht: Ist alles irgendwo beschrieben? Sondern: Ermöglicht die Dokumentation eine richtige Nutzung und eine kontrollierte Veränderung der Schnittstelle?