Ich schreibe eine klare API-Dokumentation, der Ihre Entwickler vom ersten Tag an folgen können

Warum die meisten API-Dokumentationen fehlschlagen

Sie beschreiben die Endpunkte und überspringen die Teile, die die Leute tatsächlich aufhalten: wie man sich authentifiziert, wie eine realistische Anfrage aussieht, was der Fehler bedeutet und was man dagegen tun kann. Der Leser öffnet dann ein Support-Ticket, was die Kosten sind, die die Dokumentation eigentlich vermeiden soll.

Wie ich es schreibe

Aus der Quelle, nicht aus dem Gedächtnis. Ich lese die Routen, die Validierungsschicht und die Fehlerbehandler und rufe dann die API selbst mit echten Anmeldeinformationen auf. Jedes Beispiel in der Dokumentation ist eine Anfrage, die ich gestellt habe, und eine Antwort, die ich erhalten habe – keine erfundenen Payloads, keine Statuscodes, die der Endpunkt niemals zurückgibt.

Was die Dokumentation enthält

• Authentifizierung: Erhalten eines Tokens, Aktualisieren des Tokens und was passiert, wenn es während der Sitzung abläuft.
• Jeder Endpunkt mit Parametern, eine vollständige Beispielanfrage und die tatsächliche Antwortstruktur.
• Eine Fehlerreferenz, die jeden Fehlercode einer Ursache und einer Lösung zuordnet, anstatt nur die Nachricht zu wiederholen.
• Ein Erste-Schritte-Pfad, der einen neuen Entwickler in weniger als zehn Minuten von Null zu einem erfolgreichen Aufruf führt.
• Ratenbegrenzungen, Paginierung, Webhooks und Idempotenz werden dort erklärt, wo sie tatsächlich zutreffen.

Format

Markdown in Ihrem Repository, strukturiert für OpenAPI oder eine Dokumentationsseite – was auch immer Sie tatsächlich pflegen werden. Codebeispiele in den Sprachen, nach denen Ihre Benutzer fragen, durch Ausführung verifiziert. Postman oder ähnliche Sammlung enthalten, wenn Sie eine wünschen.

Was ich brauche

Repository-Zugriff oder die OpenAPI-Datei, eine funktionierende Anmeldeinformation für eine Testumgebung und alle Fragen, deren Beantwortung Ihr Support-Team leid ist. Diese Fragen bilden die Gliederung.

Nicht enthalten

Marketingtexte. Dies dokumentiert präzise, was die Software tut; die Landingpage ist ein anderes Handwerk.

Bearbeitungszeit und Kommunikation

Ein erster vollständiger Entwurf trifft normalerweise innerhalb einer Woche ein, und Sie überprüfen ihn anhand der Fragen, die Ihr eigenes Support-Team immer wieder beantwortet. Ich lasse mich lieber frühzeitig von dem Ingenieur korrigieren, der die Grenzfälle kennt, als etwas Poliertes und Falsches zu liefern. Jedes Beispiel im endgültigen Dokument wurde gegen Ihre API ausgeführt, sodass nichts darin nur Wunschdenken ist.