API-Architektur & Validierung

Alle HTTP-Endpunkte des Fastify-Backends basieren auf strikter Schema-Validierung via Zod und standardisierten Antwortformaten.

Validierungspipeline

Jeder Request durchläuft eine 3-stufige Validierung:

1. Format- & Typvalidierung (Zod SafeParse):
   • Nicht übereinstimmende Typen oder fehlende Pflichtfelder erzeugen sofort einen 400 Bad Request mit exakter Feld-Fehlermeldung.
2. Kontext-Existenzprüfung (Directus Ping):
   • Prüft, ob referenzierte Entitäten (bookId, chapterId) in Directus existieren. Fehlt das Buch, erfolgt ein sauberer 404 Not Found.
3. Universums-Isolierung:
   • Die series_id wird serverseitig aus dem Buch abgeleitet und kann vom Client nicht manipuliert werden.

Zentrale Endpunkte

Standard-Fehlerstruktur

{
  "error": "Validation failed",
  "details": {
    "bookId": {
      "_errors": ["bookId is required"]
    },
    "messages": {
      "_errors": ["At least one message is required"]
    }
  }
}