API-Grundlagen

Die API von Document360 bietet Ihnen eine komplette, durchgängige Lösung für das Veröffentlichen, Verwalten und Testen von API-Referenzen. Egal, ob Sie ein Startup sind, das seine erste öffentliche API ausliefert, oder ein Unternehmen, das Dutzende interner Microservices betreibt – Document360 verwandelt Ihre OpenAPI-Spezifikation in eine ausgefeilte, interaktive Entwicklerdokumentation, ohne dass individuelle Werkzeuge oder manuelle Formatierungen erforderlich sind.

Das Lesererlebnis

Wenn Sie eine API-Referenz veröffentlichen, landen Entwickler auf einer interaktiven, dreiteiligen Seite – nicht auf ein statisches Dokument. Das Verständnis dieses Layouts hilft Ihnen, sich vorzustellen, was Ihre Leser tatsächlich sehen, und weist Sie auf den Artikel hin, der jeden Teil ausführlich erklärt.

• Links – Navigationsbaum. Jeder Endpunkt in deiner Spezifikation, gruppiert nach Tag in Kategorien und Unterkategorien, mit einem Methodenlabel (GET, POST, PUT, PATCH, DELETE) daneben. Leser filtern nach Namen, um schnell zu einem Endpunkt zu springen.
• Zentrum – Dokumentation. Die Beschreibung des Endpunkts, der Pfad- und Abfrageparameter, das Anforderungsschema und die Authentifizierungsanforderungen – alles generiert aus deiner Spezifikation.
• Right – Code- und Response-Panels. Fertige Beispiele für Anfragen und Beispielantworten, parallel zur Dokumentation.

Code-Panel

Das Code-Panel zeigt eine bereit zum Kopieren von Anfragen für den Endpunkt an, und Leser können die Sprache an ihren Stack anpassen. Es stehen sechs Sprachen zur Verfügung:

• cURL
• Shell
• Python
• Java
• JavaScript
• C#

Jede Probe aktualisiert sich, um den tatsächlichen Pfad, die Parameter und die Authentifizierung des Endpunkts widerzuspiegeln, sodass ein Leser sie direkt in seine eigene Umgebung kopieren kann.

Antwortpanel

Das Antwort-Panel zeigt Beispielantworten für den Endpunkt, organisiert nach Statuscode (zum Beispiel Erfolgs- und Fehlerantworten wie 200, 401, 403, 404, 422429, , 500). Die Leser wählen einen Statuscode, um die Form der Antwort zu sehen, die sie in jedem Fall erwarten sollten, was es erleichtert, sowohl Erfolgs- als auch Fehlerpfade bei ihrer Integration zu handhaben.

Probier es aus

Try It verwandelt die Referenz von etwas, das die Leser lesen , in etwas, das sie lesen können. Es öffnet eine interaktive Konsole inline an jedem Endpunkt, sodass Entwickler eine echte Anfrage senden und die Live-Antwort sehen können – Status, Timing, Header und Text –, ohne die Seite zu verlassen oder Code zu schreiben. Siehe Testen von Endpunkten mit Try it! für den vollständigen Walkthrough.

Authentifizierung

Die Leser geben die Zugangsdaten direkt in der Try It-Konsole an, mit dem Schema, das Ihre API definiert – API-Schlüssel, HTTP Basic, HTTP Bearer, OAuth 2.0 oder OpenID Connect. Try It liest die Schemata aus deiner Spezifikation und zeigt für jedes die richtigen Felder an. Siehe Autorisierung von Anfragen in der Try It-Konsole für Details zu jeder Methode.

Variablen

Variablen erlauben es Lesern, einen Wert einmal zu speichern, wie zum Beispiel eine ID oder ein Token, und ihn an jedem Endpunkt in der Referenz mit einem {{placeholder}}wiederzuverwenden. Dies erspart das Neueintippen gängiger Werte, wenn sie von einem Endpunkt zum nächsten wechseln. Siehe Verwendung von Variablen in der Try It-Konsole.

Eddy KI

Eddy AI ist in die Referenz integriert, sodass Leser Fragen zu einem Endpunkt stellen können – wie er funktioniert, wie man authentifiziert wird oder ein Codebeispiel in einer bestimmten Sprache – und Antworten erhalten können, ohne die Seite zu verlassen. Siehe Using Eddy AI in der API-Referenz.

Was ist API-Dokumentation und warum ist sie wichtig?

Die API-Dokumentation ist die technische Referenz, die Entwicklern genau sagt, wie sie mit Ihrer API interagieren sollen: welche Endpunkte existieren, welche Parameter sie akzeptieren, welche Antworten sie zurückgeben und wie die Authentifizierung funktioniert. Im Gegensatz zu allgemeinen Knowledge Base-Artikeln folgen API-Dokumente einem strengen, strukturierten Format, das aus einer maschinenlesbaren Spezifikationsdatei abgeleitet ist.

Warum es wichtig ist:

• Verkürzt die Integrationszeit. Clear Docs reduziert das Onboarding von Tagen auf Stunden. Entwickler verbringen weniger Zeit mit Raten und mehr mit dem Bauen.
• Reduziert die Unterstützungsbelastung. Wenn Dokumente die Fragen "Wie authentifiziere ich mich?" und "Was bedeutet ein 422?" beantworten, bekommt Ihr Team weniger Tickets.
• Das baut Vertrauen der Entwickler auf. Unvollständige oder veraltete API-Dokumente deuten auf ein unzuverlässiges Produkt hin. Hochwertige Dokumentation ist ein direktes Signal für Produktqualität.
• Ermöglicht Selbstbedienung. Externe Partner, Kunden und Drittentwickler können integrieren, ohne dass Ihr Team sie unterstützen muss.

API-Dokumentation vs. normale Dokumentation

In Document360 befindet sich die API-Dokumentation in einem dedizierten API-Arbeitsbereich, der von Ihrer Standard-Wissensdatenbank getrennt ist. Dies ermöglicht unterschiedliche Zugriffskontrollen, Routing und Branding für Ihre entwicklerorientierten Inhalte. Für eine vollständige Referenz aller verfügbaren Endpunkte und Schemata siehe die Document360-Entwicklerdokumentation.

Unterstützte Spezifikationsformate

Document360 unterstützt folgende Spezifikationsformate:

• OpenAPI 2.0 (früher Swagger)
• OpenAPI 3.0
• OpenAPI 3.1 (beinhaltet Webhook-Unterstützung)
• Postbotensammlungen

Dateien können als JSON, YAML oder YML hochgeladen werden.

Webhooks in OpenAPI 3.1

Document360 unterstützt Webhooks, die in OpenAPI 3.1 definiert sind. Webhooks erscheinen mit einem Ereignis-Icon in deiner API-Referenz und enthalten einen Payload-Abschnitt basierend auf deinem Schema. Wenn kein Beispiel bereitgestellt wird, zeigt Document360 ein Standardbeispiel und eine Sample-Nutzlast an. Try It! ist nicht für Webhooks verfügbar. Webhooks werden für Dateiuploads, URL-Importe und CI/CD-Flows unterstützt.

Autorisierungstechniken

Bei der Interaktion mit einer API ist es wichtig sicherzustellen, dass nur autorisierte Benutzer auf bestimmte Daten zugreifen oder bestimmte Aktionen ausführen können. Document360 unterstützt folgende Autorisierungsmethoden:

• Grunde Authentifizierung – Erfordert einen Benutzernamen und ein Passwort, die in der Anfrage übermittelt werden.
• Inhabertoken – Authentifiziert sich mit einem nach der Anmeldung generierten Token.
• API-Schlüssel – Verwendet einen eindeutigen Schlüssel, der in den Anfrageheadern übergeben wird, zur Authentifizierung.
• OAuth2 – Sichert APIs durch verschiedene Flows: Autorisierungscode, PKCE, Client-Zugangsdaten und Implicit.
• OpenID Connect – Erweitert OAuth2 durch Hinzufügen der Benutzeridentitätsverifikation.

Um Anfragen an der Document360 Customer API zu authentifizieren, benötigen Sie ein API-Token. Weitere Informationen finden Sie im Artikel über API-Token.
Um Ihre erste authentifizierte API-Anfrage mit Swagger, Postman oder Curl zu stellen, verweisen Sie auf Making your First Request.

OAuth2 und OpenID Connect: zusätzliche Konfiguration

Wenn man mit APIs arbeitet, die OAuth2 oder OpenID Connect verwenden, sind zwei Einstellungen erforderlich, damit Try It! korrekt funktioniert:

• Redirect-URI – Setzen Sie dies in Ihrem OAuth-Anbieter auf die OAuth-Callback-URL der API-Referenz: https://<your-knowledge-base-domain>/assets/apidocs-oauth-callback.html.
• Stille Verlängerung – Document360 aktualisiert das Autorisierungstoken automatisch im Hintergrund während aktiver Try It!-Sitzungen, sodass Nutzer sich nicht manuell erneut authentifizieren müssen.

FAQ