API-Designprinzipien

So funktioniert die octoja REST-API und was davon zu erwarten ist

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 einen authentifizierten Aufrufer, und octoja kennt davon zwei Arten: einen angemeldeten Benutzer und einen registrierten Agent. Beide erhalten einen eigenen Token-Typ, und jeder Endpunkt lässt nur den Typ zu, den er erwartet. Einige wenige Endpunkte antworten ganz ohne Authentifizierung, etwa GET /api/about und die Branding-Endpunkte, die die Anmeldeseite lädt, bevor sich jemand angemeldet hat. 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

API-Clients senden ein Bearer-Token im Authorization-Header. Browser-Sitzungen verwenden stattdessen das Cookie octo_session, das octoja bei jeder erfolgreichen Anmeldung setzt — auch bei einer Anmeldung über die API. 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 werden als application/problem+json gesendet und folgen RFC 7807 Problem Details for HTTP APIs mit den Standardfeldern type, title, status und detail. octoja ergänzt jeden Fehlerkörper um eine traceId — gib sie an, wenn du ein Problem meldest, denn sie kennzeichnet genau diese Anfrage in den Logs von octoja.

Wiederholungsversuche und Drosselung

Einige wenige Aktionen, die etwas nach außen senden — eine Benutzereinladung erneut senden, eine Test-E-Mail senden — haben eine kurze Wartezeit. Rufst du eine davon zu früh erneut auf, antwortet sie mit 429 Too Many Requests und einem Problem-Details-Körper, der dich um einen Moment Geduld bittet; kurz darauf funktioniert sie wieder normal.

Gestalte Clients in jedem Fall widerstandsfähig: Wiederhole Aufrufe mit exponentiellem Backoff bei 429 und bei vorübergehenden 5xx-Fehlern und beachte einen Retry-After-Header, wenn die Antwort einen enthält.

Paginierung

octoja verwendet nicht einen einzigen Paginierungsstil für die gesamte API. Welche Form ein Listen-Endpunkt nutzt, hängt davon ab, wie groß seine Sammlung werden kann — prüfe den Endpunkt also, bevor du eine Seitenschleife schreibst.

FormSo forderst du eine Seite anDas kommt zurück
Seitenweisepage (1-basiert) und pageSize — als Query-Parameter bei Listen-Endpunkten wie GET /api/assets oder als Felder im Anfragekörper bei Filter-Endpunkten wie POST /api/asset-logs/filterDie Hülle { "items": [ … ], "total": … }, wobei items die aktuelle Seite und total die Gesamtanzahl der Datensätze für die Abfrage ist
Offsetskip und limitEine einfache JSON-Liste — ohne Hülle, ohne Gesamtanzahl. Verwendet von den Zustellungsverlauf-Endpunkten: Webhooks, Microsoft-Teams-Kanäle, E-Mail-Empfänger, Gruppen für mobile Benachrichtigungen sowie jede PSA- und ITSM-Integration
VollständigGar nicht — der Endpunkt nimmt keine Paginierungsparameter entgegen und ignoriert sie, wenn du welche mitschickstEine einfache JSON-Liste mit der gesamten Sammlung. Das ist mit Abstand die häufigste Form und deckt die konfigurationsgroßen Listen ab, etwa GET /api/customers, GET /api/users und GET /api/groups

Seitenweise Endpunkte haben jeweils ihre eigene Standard- und Maximalseitengröße und begrenzen alles Größere: GET /api/assets nutzt standardmäßig 25 und maximal 500, GET /api/tickets standardmäßig 25 und maximal 100. Die genauen Parameter und Grenzen stehen im Referenzartikel des jeweiligen Endpunkts oder in der interaktiven API-Referenz.

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. Die zugrunde liegende Rohdefinition liegt unter /openapi/v1.json — darauf richtest du einen Client-Generator aus.

Verwandte Artikel