Zum Inhalt

API

Vesana hat eine REST-API unter /api/v1/. Fast alle Endpoints verlangen eine Anmeldung (Bearer-Token oder Browser-Cookie); welche Tenants eine Anfrage sieht, ergibt sich aus Rolle und Tenant-Zuordnung des angemeldeten Kontos.

  • Auth-Flow — Login, Token, 2FA, Verlängern, Step-Up, Collector-/Agent-Schlüssel vs. Benutzer-Anmeldung

  • API-Referenz — OpenAPI-Schema und Endpoint-Übersicht

  • Cookbook — typische Workflows, Code-Snippets

Allgemeine Eigenschaften

Eigenschaft Wert
Base-URL https://deine-domain.tld/api/v1
Auth Authorization: Bearer <access_token>
Content-Type application/json
Rate-Limit Login, 2FA und Step-Up: 10 Anfragen/Minute je Client-IP. Kein allgemeines Limit für die übrigen Endpoints.
Pagination Listen-Endpoints nehmen limit und offset; die Gesamtzahl steht im Antwort-Header X-Total-Count. Die Antwort bleibt ein JSON-Array.
Filter / Sortierung je Endpoint verschieden (z. B. tenant_id, q, enabled) — siehe OpenAPI-Schema. Es gibt keine generischen Filter- oder Sortier-Parameter.

Kompatibilität

Was als Breaking-Change zählt:

  • Pflichtfelder in Request-Body
  • Entfernte Endpoints
  • Geänderte Response-Schemas (Felder umbenannt, Typ geändert)

Was nicht als Breaking-Change zählt:

  • Neue optionale Felder in Request/Response
  • Neue Endpoints
  • Mehr Detail in Error-Messages

Clients sollten unbekannte Felder in Antworten ignorieren. Änderungen an der API stehen in den Release-Notes.

OpenAPI

Die API erzeugt ihr Schema selbst (/openapi.json, dazu Swagger-UI unter /docs und Redoc unter /redoc). Diese Pfade liegen im API-Container — der vorgeschaltete nginx leitet nur /api/… weiter, unter https://deine-domain.tld/docs landest du in der Web-App, nicht in Swagger.

Schema auf dem Vesana-Server exportieren:

cd /opt/vesana
docker compose exec -T api python -c \
  "import urllib.request; print(urllib.request.urlopen('http://localhost:8000/openapi.json').read().decode())" \
  > openapi.json

Die Datei lässt sich in jeden OpenAPI-Viewer oder Client-Generator laden. Endpoints von Vorschau-Funktionen (siehe Vorschau-Funktionen) stehen im Schema, antworten aber mit 404, solange die Funktion nicht freigeschaltet ist.

Anschluss