API-Grundlagen

Die API-Dokumentationsfunktion von Document360 bietet Ihnen eine komplette, durchgängige Lösung für das Veröffentlichen, Management und Testen von API-Referenzen. Egal, ob Sie ein Start-up mit der ersten öffentlichen API sind, oder ein Unternehmen mit Dutzenden interner Microservices – Document360 verwandelt Ihre OpenAPI-Spezifikation in eine ausgefeilte, interaktive Entwicklerdokumentation, ohne dass individuelle Werkzeuge oder manuelle Formatierung erforderlich sind.API

Das Lesererlebnis

Wenn Sie eine API-Referenz veröffentlichen, landen die 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, die Pfad- und Abfrageparameter des Endpunkts, das Request-Body-Schema und die Authentifizierungsanforderungen – alles generiert aus deiner Spezifikation.
• Right – Code- und Response-Panels. Fertige Beispiele für Anfragen und Beispielantworten, direkt neben der 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. Sechs Sprachen sind verfügbar:

• 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, , ). 500Die Leser wählen einen Statuscode aus, 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 wandelt die Referenz von etwas, das die Leser lesen , in etwas um, das sie ausführen können. Es öffnet eine interaktive Konsole direkt an jedem Endpunkt, sodass Entwickler eine echte Anfrage senden und die Live-Antwort sehen können – Status, Timing, Header und Body – ohne die Seite zu verlassen oder Code zu schreiben. Siehe Testing Endpoints 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 Ihrer Spezifikation und zeigt für jedes die richtigen Felder an. Siehe Authorizing Requests in der Try It-Konsole für Details zu jeder Methode.

Variablen

Variablen ermöglichen es Lesern, einen Wert einmal zu speichern, wie eine ID oder ein Token, und ihn an jedem Endpunkt in der Referenz mit einem {{placeholder}}wiederzuverwenden. Dies erspart das Nachtippen 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 nach einem 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?

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 Artikeln über die Wissensdatenbank folgen API-Dokumente einem strengen, strukturierten Format, das von einer maschinenlesbaren Spezifikationsdatei abgeleitet ist.

Warum es wichtig ist:

• Verkürzt die Integrationszeit. Klare Dokumente reduzieren das Onboarding von Tagen auf Stunden. Entwickler verbringen weniger Zeit mit Raten und mehr Zeit mit dem Aufbau.
• Verringert die Supportbelastung. Wenn die Dokumentation die Fragen "Wie authentifiziere ich mich?" und "Was bedeutet ein 422?" beantworten, bekommt dein Team weniger Tickets.
• Stärkt das Vertrauen der Entwickler. Unvollständige oder veraltete API-Dokumente signalisieren ein unzuverlässiges Produkt. Eine hochwertige Dokumentation ist ein direktes Signal für die Produktqualität.
• Ermöglicht Self-Service. 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)
• OpenAPI 3.2
• Postbotensammlungen

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

OpenAPI 3.2 fügt Unterstützung hinzu für:

• Die QUERY-HTTP-Methode für Leseoperationen, die einen Anforderungskörper benötigen
• Verschachtelte Kategorien, die automatisch aus Tag-Hierarchien generiert werden
• Der Device Authorization Flow (RFC 8628) als zusätzliche OAuth2-Option
• Streaming-Antwortschemata für Server-Send-Events und JSON-Leitungen
• Benannte Server, reichhaltigere Beispielwerte und kanonische Dokument-URIs ($self)

Webhooks in OpenAPI 3.1

Document360 unterstützt Webhooks, die in OpenAPI 3.1 definiert sind. Webhooks erscheinen mit einem Ereignissymbol in Ihrer API-Referenz und enthalten einen Payload-Abschnitt basierend auf Ihrem Schema. Falls kein Beispiel angegeben wird, zeigt Document360 ein Standardbeispiel und eine Beispielnutzlast an. Try It! ist für Webhooks nicht 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 die folgenden 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 die Document360 Customer API zu authentifizieren, benötigen Sie ein API-Token. Weitere Informationen finden Sie im Artikel zu API-Tokens .
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