Eine gut gestaltete API muss mit mindestens drei unterschiedlichen Zielgruppen kommunizieren: mit Werkzeugen, die die API programmatisch konsumieren, mit Entwicklern, die lernen oder debuggen, und mit KI-Systemen, die die API-Oberfläche verstehen müssen, um korrekten Code zu generieren oder Tool-Aufrufe zu planen. Jede Zielgruppe hat andere Anforderungen, und ein einziges Dokumentenformat kann nicht alle drei optimal bedienen. Wir lösen das, indem wir dieselbe API-Dokumentation auf drei Arten bereitstellen, die jeweils auf einen anderen Konsumenten ausgerichtet sind.
Die drei Schichten werden nicht separat gepflegt. Sie leiten sich alle aus derselben Quelle der Wahrheit ab, sodass ein neuer Endpunkt oder eine Feldänderung automatisch in alle drei Schichten propagiert — ohne manuelle Dokumentationsarbeit.
Die gesamte API-Oberfläche steht als maschinenlesbare OpenAPI-3.1-Spezifikation zur Verfügung. Das ist die Schicht, die von Code-Generatoren, Linting-Tools, SDK-Generatoren und jeder anderen Toolchain konsumiert wird, die präzise Typinformationen benötigt. Da die Spec direkt aus den eigenen Definitionen der API generiert wird statt von Hand geschrieben zu sein, kann sie nie von dem abweichen, was die API tatsächlich tut.
Die Spec umfasst alle öffentlichen und authentifizierten Endpunkte mit deklarierten Security-Schemes für API-Key- und Bearer-Token-Authentifizierung. Sie ist die maßgebliche Referenz für alle, die eine Client-Integration entwickeln oder die API mit Tools wie Postman oder Insomnia testen. Ihr findet sie verlinkt auf docs.crowdee.ai.
Neben der Spec veröffentlichen wir einen übersichtlichen, interaktiven API-Explorer, in dem Entwickler Endpoint-Dokumentation lesen, Request- und Response-Schemata inspizieren und direkt im Browser Live-Requests absenden können. Authentifizierungsdaten werden einmalig eingegeben und gelten dann für alle Requests der Session.
Wir haben uns für einen Explorer entschieden, der verschachtelte Schema-Objekte und komplexe, reale Datenstrukturen sauber darstellt, da unsere API-Oberfläche davon intensiv Gebrauch macht. Der Explorer ist das Erste, was ein Entwickler sieht, wenn er unsere API-Dokumentation öffnet — eine funktionierende, interaktive Referenz statt einer statischen Seite oder eines nackten JSON-Dokuments. Ihr könnt ihn selbst ausprobieren unter docs.crowdee.ai.
Außerdem veröffentlichen wir eine Klartext-Zusammenfassung der API, strukturiert für den Konsum durch LLMs und KI-gestützte Coding-Assistenten, nach der aufkommenden llms.txt-Konvention. Die Idee dahinter ist einfach: Sprachmodellen eine kompakte, menschenlesbare Beschreibung einer API oder Dokumentationsseite geben, ohne dass sie ein großes JSON-Dokument parsen müssen.
Unser llms.txt umfasst den gesamten Umfang der API: jede Endpoint-Gruppe, ihren Zweck, die wichtigsten Request- und Response-Felder sowie die Authentifizierungsanforderungen. Es ist öffentlich und erfordert keine Authentifizierung. Ein KI-Assistent, der es abruft, bevor er API-Aufrufe generiert, hat den Kontext, den er für gängige Integrationsmuster braucht — ein echter Vorteil, wenn ihr mit KI-Coding-Tools gegen die Crowdee-API entwickelt. Er ist zusammen mit dem Rest unserer Entwicklerdokumentation unter docs.crowdee.ai verlinkt.
Die drei Dokumentationsschichten sind das sichtbare Ergebnis einer Typsicherheits-Disziplin, die wir in unseren eigenen Anwendungen von der Datenbank bis in den Browser durchziehen. Definitionen leben an einem einzigen Ort, und alles Nachgelagerte — Validierung, API-Dokumentation und die Client-Bibliotheken, die unsere eigenen Frontend-Teams nutzen — wird aus dieser einen Quelle abgeleitet, statt manuell synchron gehalten zu werden.
Was das in der Praxis bedeutet: Wenn unsere internen Teams die API aus unseren eigenen Anwendungen heraus aufrufen, erhalten sie Autovervollständigung für jeden Request-Parameter und jedes Response-Feld. Ändert sich das zugrundeliegende Datenmodell, aktualisieren sich die Validierungsregeln, die API-Dokumentation und die internen Client-Bibliotheken gemeinsam, in einem Schritt. Die drei Dokumentationsendpunkte spiegeln dieselbe Änderung wider, ohne manuellen Eingriff.
Diese Disziplin sorgt auch dafür, dass die OpenAPI-Spec nie veraltet. Sie wird aus den Live-Definitionen der API generiert, nicht aus einer eingecheckten Datei, deren Aktualisierung jemand vergessen hat. Der interaktive Explorer und der llms.txt-Endpunkt konsumieren dieselben Live-Definitionen. Was man im Explorer sieht, entspricht immer dem, was die API tatsächlich tut.
Artikel teilen:
