Von der Anfrage zu Doku, die jemand liest
API-Dokumentation verrottet, weil sie getrennt von den Anfragen geschrieben wird. Aus der Sammlung erzeugt ist die einzige Fassung, die wahr bleibt.
Die meiste API-Dokumentation lügt ab dem dritten Monat. Nicht weil jemand gelogen hätte — sondern weil die Doku an einem Ort lebt und die Anfragen an einem anderen, und nur eines von beidem aktualisiert wird, wenn sich ein Feld ändert.
Lodos schließt diese Lücke, indem die Dokumentation aus der Sammlung erzeugt wird, gegen die Sie ohnehin testen. Das ist der ganze Sinn dieser zwei Module nebeneinander, und es verändert, wie Sie die Sammlung vom ersten Tag an ordnen sollten.
Die Sammlung für die Doku ordnen, nicht für sich selbst
API Post/Get unterstützt alle HTTP-Methoden, Sammlungen mit Ordnern, Header- und Auth-Verwaltung sowie einen Antwortbetrachter mit Syntaxhervorhebung. Die Ordnerstruktur, die Sie wählen, wird zur Struktur Ihrer Dokumentation — fünf Minuten Nachdenken lohnen sich.
Gruppieren Sie nach Ressource, nicht nach Aufgabe. Ein Ordner users mit Auflisten, Anlegen, Ändern und Löschen liest sich wie Dokumentation. Ein Ordner Onboarding-Ablauf mit drei Anfragen aus drei Ressourcen liest sich wie Ihr persönlicher Notizzettel, denn genau das ist er.
Benennen Sie Anfragen im Vokabular der API. GET /users/:id ist besser als einen Nutzer holen, weil die lesende Person das Gesehene mit dem Endpunkt abgleichen will, den sie aufruft.
Umgebungsvariablen entscheiden über die Lebensdauer
Das ist der Unterschied zwischen einer Sammlung, die ein Jahr hält, und einer, die beim ersten Umzug von Staging aufhört zu funktionieren.
Legen Sie jeden Host, jedes Token und jede wechselnde Kennung in eine Umgebungsvariable. {{base_url}}/users/{{test_user_id}} ist eine Anfrage, die lokal, in Staging und in Produktion funktioniert, indem Sie ein Auswahlfeld umstellen. Eine Anfrage mit https://staging-2.example.com fest in der URL bricht in drei Wochen still und wird von der nächsten Person neu geschrieben, die sie braucht.
Pre-Request-Skripte lösen den Fall, an dem die meisten hängen bleiben: ein Auth-Token, das abläuft. Holen Sie es in einem Vorab-Schritt und legen Sie es in eine Umgebungsvariable — dann hören Sie auf, jeden Morgen ein frisches Bearer-Token in elf Anfragen zu kleben.
Zugangsdaten, ehrlich betrachtet
Eine Sammlung gehört zum Workspace, das heißt: Jede Person mit Zugriff sieht sie — inklusive der Werte in Ihren Umgebungen.
Behandeln Sie das als die Randbedingung, die es ist. Entwicklungs- und Staging-Zugangsdaten in der Sammlung sind in Ordnung und wirklich nützlich; wer Ihre Arbeit übernimmt, sollte nicht danach suchen müssen. Produktionszugangsdaten sind nicht in Ordnung. Wenn ein Wert auf einem Screenshot ein Problem wäre, gehört er nicht in eine geteilte Umgebung.
Der praktische Aufbau: eine Umgebung pro Stufe, Produktion bewusst unvollständig, damit ein Lauf gegen Produktion eine bewusste Handlung erfordert und nicht die falsche Auswahl im Dropdown.
Daraus Dokumentation machen
API Documentation erzeugt aus der Sammlung und legt darüber einen Rich-Text-Editor, Versionsverwaltung, Code-Snippet-Erzeugung, PDF-Export und teilbare Links.
Der erzeugte Teil deckt ab, was der Endpunkt ist und was er entgegennimmt. Was er nicht wissen kann, ist, warum ihn jemand aufrufen würde — und genau das braucht die lesende Person. Das Muster, das funktioniert:
- Aus der Sammlung erzeugen. Die Endpunktliste nicht von Hand schreiben; sie driftet.
- Pro Ressource einen kurzen Absatz ergänzen, wofür sie da ist und wann man sie benutzt.
- Die Fehler dokumentieren. Nicht die 200 — die 409, die bedeutet, dass die E-Mail vergeben ist, und was der Client damit tun soll.
- Einen Link veröffentlichen statt PDF zu exportieren, sofern niemand ausdrücklich eine Datei braucht. Ein Link bleibt aktuell; ein PDF ist die Fotografie eines Moments.
Versionsverwaltung zählt, sobald Sie externe Nutzer haben. Schneiden Sie eine Version an dem Punkt, an dem jemand anfängt, dagegen zu bauen — damit es nach einer Änderung noch ein Dokument gibt, das beschreibt, wogegen gebaut wurde.
Die 130 kleinen Dinge
Gut zu wissen, weil es einen Browsertab spart: Das Modul Tools enthält über 130 Hilfsprogramme — JSON- und XML-Formatierer, Encoder, Konverter, Hash-Generatoren. Sie laufen vollständig im Browser, nichts wird hochgeladen, und sie kosten keine Token.
Das letzte Detail wiegt schwerer, als es klingt. Ein Payload in einen beliebigen Online-JSON-Formatierer zu kleben heißt, Ihre Daten auf den Server einer fremden Person zu kleben. Stehen Kundendaten darin, ist das ein kleiner Vorfall, den niemand je bemerkt. Das lokale Werkzeug nimmt die Versuchung weg.
Häufig gestellte Fragen
Kann ich eine bestehende Sammlung importieren?
Sammlungen werden in API Post/Get mit Ordnern, Headern, Auth und Umgebungen aufgebaut. Wenn Sie von einem anderen Werkzeug kommen, bauen Sie die tatsächlich genutzten Anfragen neu, statt alles zu importieren — die meisten Sammlungen schleppen jahrelang tote Endpunkte mit.
Wer sieht die Zugangsdaten in meinen Umgebungen?
Alle mit Zugriff auf den Workspace. Entwicklungs- und Staging-Werte gehören dorthin, Produktionswerte nicht. Der Test ist einfach: Wäre ein Wert auf einem Screenshot ein Problem, gehört er nicht in eine geteilte Umgebung.
Aktualisiert sich die Doku, wenn ich eine Anfrage ändere?
Der erzeugte Teil kommt aus der Sammlung, ein erneutes Erzeugen übernimmt die Änderung. Von Hand geschriebener Text bleibt, wie er ist — deshalb sollte der handgeschriebene Teil erklären, warum ein Endpunkt existiert, statt seine Parameter zu wiederholen.
PDF exportieren oder Link teilen?
Einen Link, sofern niemand ausdrücklich eine Datei braucht. Ein geteilter Link zeigt die aktuelle Fassung; ein PDF ist die Aufnahme eines Moments und wird schon am Tag nach dem Versand falsch.
