API-Referenz

Backend-API

Alle Endpunkte des core-backend liegen unter der Basis-URL /api/v1. Der Request-Body wird stets mit Zod validiert, alle Antworten sind JSON. Aus historischen Gründen verwenden auch Lesezugriffe die POST-Methode.

Basis-URL

Alle in dieser Referenz aufgeführten Pfade sind relativ zur Backend-Basis-URL. Für lokale Entwicklung ist das üblicherweise http://localhost:4000.

Base URL{host}/api/v1

Eine interaktive Swagger-UI ist im Entwicklungsmodus unter /api/v1/swagger erreichbar. Die OpenAPI-Spezifikation lässt sich mit npm run script:create_openapi_file generieren.

Authentifizierung

Das Backend kennt drei Nutzerrollen mit jeweils eigener Authentifizierungsmethode. Session-Tokens werden als SHA-256-Hashes in der Datenbank gehalten.

Rolle	Cookie / Header	Beschreibung
Super-Admin	`x-super-admin-api-key` oder Cookie `superAdminSession`	Systemweite Verwaltung
Lehrkraft	`teacherSession`	Schulbezogene Verwaltung, Rollen admin und teacher
Schüler:in	`studentSession`	Lern-Zugang

Middleware-Pipeline

Jeder Request durchläuft in dieser Reihenfolge: cors · helmet · requestIdMiddleware · loggerMiddleware · express.json (50 MB) · Route-spezifische authMiddleware und validateBody · Controller · errorMiddleware.

Fehlerformat

Fehlerantworten folgen zwei einheitlichen Schemas: clientErrorResponse für validierbare Client-Fehler und serverErrorResponse für unerwartete Server-Fehler.

JSONHTTP 400 · Beispiel

{
  "type": "clientError",
  "message": "Validation failed",
  "requestId": "01H…",
  "issues": [
    { "path": ["email"], "message": "Invalid email" }
  ]
}

Super-Admin

Systemweite Verwaltung. Erfordert Super-Admin-Berechtigung.

Basispfad: /api/v1/super-admin

Schulen

Schulen anlegen und Einladungen erstellen.

Basispfad: /api/v1/school

Lehrkräfte

Registrierung, Anmeldung und Abmeldung von Lehrkräften.

Basispfad: /api/v1/teacher

Schüler:innen

Registrierung und Anmeldung von Schüler:innen.

Basispfad: /api/v1/student

Fachbegriffe

Verwaltung von Fachbegriffen und Bild-Scan durch Schüler:innen.

Basispfad: /api/v1/technical-term

Klassen & Arbeitsaufträge

Klassen anlegen, PDFs einreichen, Fortschritt abfragen und Mitglieder verwalten.

Basispfad: /api/v1/class

Quiz

Quiz-Antworten einreichen und individuellen Fortschritt abrufen.

Basispfad: /api/v1/quiz

Sonstige

Basispfad: /api/v1

ML-Service (intern)

Nur intern über das Backend erreichbar. Details siehe ML-Service-Doku.

Basispfad: http://ml-service:8000