Gültig ist nur der Anfang
Ein aus dem Schema erzeugtes Beispiel kann syntaktisch korrekt und didaktisch wertlos sein. string, 123 und foo bestehen Validatoren, verbergen aber die Domäne. Ein gutes Example zeigt, warum der Request existiert und was der erfolgreiche Response ermöglicht.
Nutze realistische Werte ohne echte Secrets oder personenbezogene Daten.
Baue eine kleine Geschichte
Bevorzuge eine Sequenz wie in einer echten Aufgabe: Resource anlegen, lesen, aktualisieren und einen Fehler oder Cleanup behandeln. Wiederverwende IDs, damit Beziehungen sichtbar werden.
Auf einzelnen Reference-Seiten ist ein Link zum passenden Workflow besser als ein kopiertes Komplett-Tutorial.
Zeige den wichtigen Response
Höre nicht beim Request auf. Zeige Status, relevante Headers und Body. Erkläre wenig offensichtliche Felder. Bei asynchronen Operations muss klar sein, wie der Client den Abschluss erkennt.
Realistische Error Examples sind genauso wichtig.
Mache Examples ausführbar
Führe Requests nach Möglichkeit in CI aus oder validiere Payloads gegen den Contract. Speichere Samples als Dateien oder generierte Snippets statt als manuelle Kopien auf mehreren Seiten.
Optimiere für Übertragbarkeit
Erkläre, welche Werte der Leser ändern soll und welche Voraussetzungen gelten. Ziel ist ein übertragbares mentales Modell.
Wenn das Example den nächsten Request nicht leichter macht, ist es wahrscheinlich Dekoration.
Praxisbeispiel
Mach aus „API-Beispiele sollten einen Workflow lehren, nicht die Reference dekorieren“ 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
- Gültig ist nur der Anfang. Ein aus dem Schema erzeugtes Beispiel kann syntaktisch korrekt und didaktisch wertlos sein.
- Baue eine kleine Geschichte. Bevorzuge eine Sequenz wie in einer echten Aufgabe: Resource anlegen, lesen, aktualisieren und einen Fehler oder Cleanup behandeln.
- Zeige den wichtigen Response. Höre nicht beim Request auf.
- Mache Examples ausführbar. Führe Requests nach Möglichkeit in CI aus oder validiere Payloads gegen den Contract.
