Zum Inhalt

API

Vesana hat eine REST-API unter /api/v1/. Alle Endpoints sind JWT-geschützt, Tenant-Scope ist implizit aus dem Token.

  • Auth-Flow — Login, JWT, 2FA, Refresh, Personal-Access-Tokens

  • API-Referenz — interaktive OpenAPI-Doku

  • Cookbook — typische Workflows, Code-Snippets

Allgemeine Eigenschaften

Eigenschaft Wert
Base-URL https://deine-domain.tld/api/v1
Auth Authorization: Bearer <jwt>
Content-Type application/json
Rate-Limit Login/2FA: 10 req/min/IP, sonstige: 600 req/min/User
Pagination ?limit=50&offset=0 oder ?cursor=...
Filter ?<field>=<value> und ?q=<volltext>
Sortierung ?sort=<field> und ?order=asc|desc

Stabilitätsgarantien

/api/v1/ ist stabil — Breaking-Changes nur bei Major-Release-Wechsel mit Migrations-Plan und Deprecation-Phase.

/api/v2/ (zukünftig) wird parallel laufen, falls eingeführt — v1 bleibt mindestens zwei Major-Releases erhalten.

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

Versionierungs-Header

Antwort-Header X-Vesana-Version: 0.19.0 zeigt Server-Version. Im Body kein Version-Info — wenn du gegen verschiedene Server-Versionen testest, Header lesen.

OpenAPI

Die API ist FastAPI-basiert, das Schema liegt unter:

GET /openapi.json

Swagger-UI:

GET /docs

Redoc:

GET /redoc

In der docs.vesana-Site siehst du die Referenz unter API-Referenz (eingebettet).

Anschluss