Ihre API-Dokumentation listet 47 Endpunkte auf. Jeder hat die HTTP-Methode, den Pfad, den Request-Body und das Response-Schema. Sie ist vollständig, korrekt und völlig nutzlos.
Warum? Weil ich, wenn ich auf Ihre Dokumentation stoße, in der Regel kein Endpunkt-Verzeichnis möchte.
Ich möchte eine Aufgabe erledigen.
Ich möchte wissen, wie ich den Kunden anlege, die Zahlungsmethode hinterlege, das Abonnement starte, den Webhook verarbeite, Fehler behebe und alles sicher teste.
Eine Endpunkt-Referenz ist notwendig. Sie ist nicht das Produkt.
Referenz ist nicht Einarbeitung
Eine Referenzseite beantwortet:
- Welcher Pfad existiert
- Welche Methode er akzeptiert
- Welche Felder erlaubt sind
- Wie die Antwort aussieht
Einarbeitung beantwortet:
- Was soll ich zuerst tun?
- In welcher Reihenfolge laufen diese Aufrufe ab?
- Was kann fehlschlagen?
- Was soll ich speichern?
- Wie teste ich das, ohne die Produktion zu gefährden?
Wenn Ihre Dokumentation nur Referenzseiten hat, muss der Entwickler den Workflow aus Einzelteilen rückentwickeln.
Deshalb können sich „vollständige“ Dokumentationen trotzdem unbrauchbar anfühlen.
Beginnen Sie mit den Aufgaben, die Entwickler tatsächlich haben
Für die meisten APIs sollte die eigentliche Dokumentation mit Aufgabenpfaden beginnen:
- Eine Anfrage authentifizieren
- Die erste Ressource erstellen
- Die Ressource sicher aktualisieren
- Auf einen Webhook lauschen
- Einen fehlgeschlagenen Vorgang wiederholen
- Vom Testmodus in die Produktion wechseln
Jede Aufgabe kann dann auf die Endpunkt-Referenz verlinken.
Die Anleitung beginnt mit dem Entwicklerziel, zeigt einen funktionierenden Pfad, enthält Beispiele und verlinkt dann auf die genauen Endpunkt-Details.
Die Reihenfolge ist wichtig. Wenn die erste Seite eine riesige Referenztabelle ist, bitten Sie den Leser, das mentale Modell allein aufzubauen.
Zeigen Sie einen vollständigen Pfad, keine isolierten Aufrufe
Schlechte Dokumentation zeigt eine perfekte Anfrage:
POST /customersBessere Dokumentation zeigt die Abfolge:
- Kunden anlegen.
- Abonnement erstellen.
- Die zurückgegebenen IDs speichern.
- Auf den Bestätigungs-Webhook lauschen.
- Fehler- und Kündigungszustände behandeln.
Die Abfolge ist das, was Entwickler brauchen, um die Integration auszuliefern.
Noch besser: Fügen Sie die Form des Zustandsautomaten hinzu:
