API-Überblick¶

Die Kamerplanter-API ist eine REST-API, die auf FastAPI basiert. Alle Endpunkte geben JSON zurück und folgen etablierten HTTP-Konventionen. Eine interaktive Dokumentation mit Swagger UI steht unter /api/v1/docs bereit.

Basis-URL¶

http://localhost:8000/api/v1

In Produktionsumgebungen wird die API über Traefik als Ingress-Controller unter der konfigurierten Domain erreichbar.

Interaktive Dokumentation¶

Deployment-Modi¶

Das Verhalten der API hängt vom konfigurierten Deployment-Modus ab. Den aktuellen Modus liefert der Mode-Endpunkt:

GET /api/v1/mode

{
  "mode": "full",
  "features": {
    "auth": true,
    "multi_tenant": true,
    "privacy_consent": true
  }
}

full (Standard)¶

Vollständiger Betrieb mit Authentifizierung, Mandantenverwaltung und DSGVO-Funktionen. Alle Auth-Endpunkte sind aktiv. Jede Anfrage muss authentifiziert sein (außer health, mode und öffentliche OAuth-Callbacks).

light¶

Aktiviert durch KAMERPLANTER_MODE=light. Kein Login erforderlich — alle Endpunkte sind ohne Authentifizierung zugänglich. Geeignet für lokale Einzelnutzer-Installationen ohne Multi-Tenant-Bedarf. Die Auth-Router (/auth/...) sind in diesem Modus deaktiviert.

URL-Struktur¶

Die API unterscheidet zwischen globalen Ressourcen und mandantengebundenen Ressourcen.

Globale Ressourcen¶

Stammdaten wie Pflanzenarten, botanische Familien und IPM-Referenzdaten sind global — sie gehören keinem einzelnen Mandanten.

GET  /api/v1/species/
GET  /api/v1/species/{key}
GET  /api/v1/botanical-families/
GET  /api/v1/cultivars/
GET  /api/v1/ipm/pests/
GET  /api/v1/starter-kits/

Mandantengebundene Ressourcen¶

Alle nutzerspezifischen Daten (Pflanzen, Durchläufe, Sensoren, Tanks usw.) sind einem Mandanten zugeordnet und werden über den Mandanten-Slug in der URL adressiert:

/api/v1/t/{tenant_slug}/...

Beispiele:

GET  /api/v1/t/mein-garten/plant-instances/
POST /api/v1/t/mein-garten/planting-runs/
GET  /api/v1/t/mein-garten/tanks/
GET  /api/v1/t/mein-garten/tasks/

Der Tenant-Slug wird bei der Registrierung automatisch aus dem Nutzernamen generiert (persönlicher Mandant). Für Gemeinschaftsgärten kann ein separater Mandant angelegt werden.

Health-Endpunkte¶

Die Health-Endpunkte erfordern keine Authentifizierung und sind für Kubernetes-Liveness- und Readiness-Probes vorgesehen:

GET /api/v1/health/live    → {"status": "alive"}
GET /api/v1/health/ready   → {"status": "ready", "database": true}
GET /api/health            → {"status": "healthy", "version": "...", "mode": "..."}

Endpunkt-Übersicht¶

Die folgende Tabelle listet alle verfügbaren Router-Gruppen. Im Full-Modus sind auth-, oidc-providers- und platform-admin-Routen zusätzlich aktiv.

Anfrage- und Antwortformat¶

Alle Request-Bodies und Responses verwenden application/json. Eine explizite Content-Type: application/json-Kopfzeile ist für POST/PUT/PATCH-Anfragen erforderlich.

Paginierung¶

Listenendpunkte unterstützen skip und limit als Query-Parameter:

GET /api/v1/species/?skip=0&limit=50

Standardwerte: skip=0, limit=100 (je nach Endpunkt variierend).

Datumsformat¶

Alle Datums- und Zeitangaben folgen ISO 8601 im UTC-Format:

2026-03-17T10:30:00Z

Rate Limiting¶

Zur Missbrauchsvermeidung sind sensible Endpunkte mit Rate Limits versehen:

Bei Überschreitung antwortet die API mit HTTP 429 Too Many Requests.

CORS-Konfiguration¶

Erlaubte Origins werden über die Umgebungsvariable CORS_ORIGINS als kommagetrennte Liste konfiguriert:

CORS_ORIGINS=https://app.kamerplanter.example.com,https://admin.kamerplanter.example.com

Standardmäßig sind http://localhost:3000 und http://localhost:5173 (Vite-Dev-Server) erlaubt.

Sicherheits-Header¶

Jede API-Antwort enthält folgende Sicherheits-Header:

Siehe auch¶

• Authentifizierung — Token-Workflow und API-Keys
• Fehlerbehandlung — Fehlerstruktur und Fehlercodes
• Lokale Entwicklungsumgebung — Backend lokal starten