API-Designprinzipien
So funktioniert die octoja REST-API und was davon zu erwarten ist
Geschrieben von Erdinc Akay
Zuletzt aktualisiert Vor 26 Tagen
API-Designprinzipien
Die octoja-API ist die HTTP-Schnittstelle, über die das octoja-Web-Dashboard und die octoja-Agenten mit der octoja-Plattform kommunizieren — und dieselbe Schnittstelle, die du direkt aufrufen kannst, um programmatisch mit deinen Daten zu arbeiten. Sie ist keine separat versionierte öffentliche API; Endpunkte können sich zwischen Releases ändern. Betrachte daher die aktuelle OpenAPI-Beschreibung als verbindliche Quelle, statt dich auf eine feste Form zu verlassen. Fast jeder Endpunkt erfordert eine authentifizierte Sitzung — eine Benutzersitzung, eine Kundenkonto-Sitzung oder ein Agenten-Credential. Einige wenige Endpunkte sind anonym, etwa GET /api/about. Dieser Artikel beschreibt die Konventionen dieser Schnittstelle, damit du weißt, was dich in Traces, Logs und verwandter Entwicklerdokumentation erwartet.
REST und JSON
octoja nutzt HTTPS-Endpunkte mit JSON-Anfrage- und -Antwortkörpern.
Authentifizierung
Authentifizierte API-Anfragen verwenden ein Bearer-Token im Authorization-Header. Details zu Anmeldung, Token-Erneuerung und Sitzungen stehen im Artikel zur API-Authentifizierung.
HTTP-Statuscodes
Die API verwendet die üblichen HTTP-Statuscodes, um Erfolg, Validierungsprobleme, Autorisierungsfehler und fehlende Ressourcen anzuzeigen.
Antwortformat
Erfolgreiche Antworten liefern die angeforderten Daten zurück. Fehlerantworten folgen RFC 7807 Problem Details for HTTP APIs mit den Standardfeldern type, title, status und detail.
Rate Limiting
Gestalte Clients widerstandsfähig: Implementiere Wiederholungsversuche mit exponentiellem Backoff und beachte einen etwaigen Retry-After-Header bei Drosselung oder vorübergehenden Fehlern.
Paginierung
Die meisten Listen-Endpunkte akzeptieren die Query-Parameter page (1-basiert) und pageSize, wenden eine Standard- und eine maximale Seitengröße an und antworten mit der Hülle { Items, Total }, wobei Items die aktuelle Seite und Total die Gesamtanzahl der Datensätze für die Abfrage ist. Es gibt Ausnahmen: Die Zustellungs-Endpunkte (Webhook-Zustellungen, Microsoft-Teams-Zustellungen, Woasi-Zustellungen) verwenden stattdessen die Parameter skip und limit und liefern eine einfache Liste ohne Hülle zurück. Die genaue Standard- und Maximalseitengröße unterscheidet sich je Endpunkt — die genauen Parameter und Grenzen stehen im Referenzartikel des jeweiligen Endpunkts.
Interaktive API-Referenz
octoja liefert eine vollständige, interaktive API-Referenz, die direkt aus der OpenAPI-Definition der Plattform generiert wird. Da sie aus dem laufenden Code erstellt wird, stimmt sie immer mit den aktiven Endpunkten überein — betrachte sie als die maßgebliche Quelle für genaue Pfade, Query-Parameter, Anfragekörper und Antwortfelder. Die Artikel in diesem Abschnitt dienen der Orientierung; die interaktive Referenz enthält die vollständigen Details zu jedem einzelnen Endpunkt.
Um sie zu öffnen, hänge /openapi an deine octoja-Web-Adresse an — dieselbe Adresse, unter der du dich beim Dashboard anmeldest (zum Beispiel https://your-octoja-address/openapi). Sie ist jederzeit verfügbar. Um einen Aufruf auszuprobieren, der eine Authentifizierung erfordert, verwende die Schaltfläche Authorize und füge ein Bearer-Token ein.