Ein typisches Produktionsproblem: Ein Client schickt ein Feld als String statt Zahl, ein optionales Objekt fehlt oder ein Array enthält leere Elemente. Ohne konsequente Validierung rutschen solche Payloads in Business-Logik, erzeugen Seiteneffekte und enden als schwer nachvollziehbare Fehler in späteren Schichten. Der wichtigste Hebel dagegen ist Schema-Validation: Daten werden früh geprüft, klar abgelehnt oder normiert, bevor sie Schaden anrichten.
Im API-Kontext bedeutet das mehr als „required“-Felder: Typen, Formate, Grenzwerte, erlaubte Werte, Objektstrukturen, sowie die Frage, wie Fehler an Clients kommuniziert werden. Außerdem sollte nicht nur der Request, sondern auch die Response geprüft werden, um unbeabsichtigte Vertragsbrüche zu erkennen.
Warum Validierung im API-Layer stattfinden sollte
Fehlerkosten steigen mit jeder Schicht
Je später ein ungültiger Input entdeckt wird, desto teurer wird er: Die Business-Logik läuft an, Queries werden ausgeführt, Events werden erzeugt, möglicherweise werden Drittsysteme aufgerufen. Frühzeitige Validierung stoppt den Request am Rand des Systems, nahe am HTTP-Handler oder Controller, mit einer eindeutigen Fehlermeldung.
Ein praxistaugliches Ziel: Ungültige Payloads dürfen die Domain-Schicht gar nicht erreichen. Dadurch wird die Domäne einfacher, weil sie von „sauberen“ Typen ausgehen kann (z. B. ein Money-Value-Object statt „number | string | null“).
Verträge werden explizit statt implizit
Ohne formale Schemata entstehen Verträge durch Beispiel-JSONs, Wiki-Seiten und „so wird es schon passen“. Das bricht spätestens, wenn mehrere Clients oder Teams beteiligt sind. Eine OpenAPI-Spezifikation (für REST/HTTP) macht Felder, Typen und Fehlercodes sichtbar und ist eine gute Basis für Generatoren, Tests und Doku.
Welche Regeln in ein Schema gehören (und welche nicht)
Was Schema-Validation zuverlässig leisten kann
Schema-Validation ist stark bei Struktur und Datentypen. Typische Regeln, die im Schema gut aufgehoben sind:
- Pflichtfelder, optionale Felder, verbotene Felder (z. B. „keine zusätzlichen Properties“).
- Datentypen und Formate (ISO-8601 für Datumsstrings, UUID-Pattern, E-Mail-Format).
- Grenzwerte (min/max), Längenbegrenzungen, erlaubte Enum-Werte.
- Abhängigkeiten zwischen Feldern (z. B. „entweder A oder B“), wenn das Schema-Format es unterstützt.
Wichtig ist die Trennung zwischen syntaktischer Validierung und fachlicher Validierung. Das Schema sollte beschreiben, wie Daten aussehen müssen, nicht ob eine Geschäftsregel erfüllt ist („Benutzer darf Rabatt anwenden“).
Business-Regeln gehören in Domain-Logik
Fachliche Regeln hängen oft von Datenbankzustand, Berechtigungen oder Zeitpunkten ab. Beispiele: „E-Mail muss einzigartig sein“, „Produkt ist verfügbar“, „Limit pro Kunde“. Solche Regeln sollten als Domain-Validierung implementiert werden, idealerweise nahe an den Use-Cases, damit sie testbar und evolvierbar bleiben.
Request-Validierung: Ablauf und Fehlerformat
Validieren, normalisieren, typisieren
Ein belastbarer Request-Pfad besteht aus drei Schritten: (1) Validieren, (2) Normalisieren (z. B. Trimmen von Strings, Default-Werte setzen), (3) Typisieren/Mapping auf interne DTOs oder Value Objects. In vielen Codebasen passiert das gemischt; wartbarer ist eine klare Pipeline.
In TypeScript-Backends wird häufig ein Runtime-Schema (z. B. JSON Schema oder Bibliotheken mit Schema-Definition) genutzt, um aus „unknown“ ein „typed object“ zu machen. Entscheidend: Die Typisierung darf nicht nur im Compiler existieren; sie muss zur Laufzeit abgesichert werden, sonst bleiben es Annahmen.
Klare 400er-Fehler ohne Informationsleck
Bei ungültigen Requests sollte die API mit einem 400er antworten, inklusive maschinenlesbarer Details. Ein praxistaugliches Fehlerobjekt enthält:
- Einen stabilen Fehlercode (z. B. „VALIDATION_ERROR“).
- Eine Liste einzelner Feldfehler mit Pfad (z. B.
items[2].price), erwarteter Regel und einer kurzen Nachricht. - Keine internen Stacktraces oder Bibliotheks-Fehlertexte, die Implementation Details preisgeben.
Das reduziert Support-Aufwand, weil Clients präzise sehen, was korrigiert werden muss. Gleichzeitig bleibt die Oberfläche stabil, selbst wenn die Validierungsbibliothek gewechselt wird.
Response-Validierung: Vertragsbrüche im Server entdecken
Warum Responses ebenfalls geprüft werden sollten
Viele Teams validieren nur Requests. In der Praxis entstehen Vertragsbrüche aber genauso oft serverseitig: Ein Feld wird umbenannt, ein neuer Enum-Wert rutscht rein, ein Optional wird plötzlich immer null. Response-Validation wirkt wie eine Alarmanlage: Der Server merkt, wenn er etwas zurückgibt, das nicht zum Vertrag passt.
Gerade bei refactorings, Feature-Flags oder mehreren Serializer-Pfaden ist das wertvoll. Die Validation kann in Tests strikt sein und in Produktion selektiv (z. B. sampling-basiert), um Overhead zu kontrollieren.
Wie strikt muss Response-Validation sein?
Response-Validierung ist ein Trade-off zwischen Sicherheit und Performance. Sinnvolle Abstufungen:
- In CI und Staging: strikt für alle Responses.
- In Produktion: nur für bestimmte Endpoints, nur bei neuen Releases oder als Stichprobe.
- Bei besonders kritischen Integrationen: dauerhaft strikt.
Wenn Response-Validation fehlschlägt, sollte ein Serverfehler entstehen (5xx) und ein internes Signal an Monitoring/Alerting gehen. Der Client kann den Fehler nicht beheben; das Problem liegt im Server.
Integration in Toolchain und Deployment
Schema als Single Source of Truth
Wenn OpenAPI/JSON-Schema gepflegt wird, sollte es nicht nur Dokumentation sein. Gute Praxis ist eine „Single Source of Truth“: Entweder wird das Schema aus Code generiert (code-first) oder Code/Clients werden aus dem Schema generiert (schema-first). Entscheidend ist Konsistenz: Doppelte Definitionen führen zu Drift.
In Teams mit mehreren Services lohnt sich zusätzlich eine Contract-Test-Stufe: Provider publiziert das Schema, Consumer testen gegen kompatible Änderungen. Das reduziert Breaking Changes in verteilten Systemen.
Validierung in CI: schneller Fail statt später Bug
Für CI/CD bieten sich drei Ebenen an: Linting der Spezifikation, Tests für Request/Response-Validierung und Regressionstests für Breaking Changes. Datenbanknahe Änderungen sollten mit Migrationspipelines abgestimmt werden; dafür passt thematisch auch der Beitrag zu Datenbankmigrationen in CI/CD, weil Validierung und Migrationen gemeinsam bestimmen, welche Payloads persistiert werden dürfen.
Typische Stolpersteine aus realen API-Projekten
Zusätzliche Felder: tolerant oder strikt?
Manche Clients senden mehr Felder als dokumentiert (z. B. alte App-Versionen oder generische SDKs). Strikte Ablehnung („no additional properties“) ist sauber, kann aber Rollouts bremsen. Ein pragmatischer Ansatz: Für Create/Update strikt sein, für Read toleranter. Alternativ zusätzliche Felder erlauben, aber explizit ignorieren und nicht persistieren.
Numerische Werte und Präzision
JSON kennt nur „number“. Bei Geldbeträgen entstehen Präzisionsprobleme. Schema-Validation kann zwar min/max prüfen, löst aber nicht das Float-Thema. Bewährt ist, Geld als Integer in kleinster Einheit (z. B. Cent) oder als String mit festem Format zu transportieren und in der Domain als Value Object zu behandeln.
Idempotenz und Validierung greifen ineinander
Wenn Clients bei Timeouts retried werden, kommen Requests doppelt. Strikte Validierung hilft zwar gegen Müll, verhindert aber keine Doppelverarbeitung. Für robuste Endpoints lohnt das Zusammenspiel mit idempotenten APIs: Validierung stellt „korrekte Form“ sicher, Idempotenz „korrekte Wirkung“.
Konkrete Umsetzungsschritte für ein API-Team
Schrittfolge, die in bestehenden Services funktioniert
- Pro Endpoint ein Request- und Response-Schema definieren und versionieren.
- Im HTTP-Layer einheitliche Validierungs-Middleware einziehen (vor Auth/Business-Logik nur, wenn Auth keine Body-Felder braucht).
- Fehlerformat standardisieren: stabiler Code, Feldpfad, kurze Nachricht; keine Bibliotheks-Details.
- Normalizer ergänzen: Default-Werte, Trimming, Koerzierung nur wenn explizit gewünscht und dokumentiert.
- In Tests Response-Validation aktivieren und Snapshots/Fixtures gegen das Schema laufen lassen.
- Breaking-Change-Checks in CI etablieren (z. B. Schema-Diff gegen letzte Release-Version).
Entscheidungen: Wo Validierung am meisten bringt
Kurzer Entscheidungsbaum für Prioritäten
- Viele externe Clients oder Partner?
- Request-Validation strikt + stabiles Fehlerformat priorisieren.
- Response-Validation mindestens in CI/Staging aktivieren.
- Hohe Änderungsfrequenz im Backend?
- Response-Validation in Tests und bei kritischen Endpoints auch in Produktion (stichprobenartig).
- Komplexe Payloads (Nested Objects, Arrays, Polymorphie)?
- Schema-first Ansatz und Generatoren erwägen, um Drift zu vermeiden.
- Hohe Last und sehr niedrige Latenz-Ziele?
- Validierung optimieren: nur notwendige Checks, kompiliertes Schema, Sampling für Response-Checks.
Zusammenspiel mit Observability und Betrieb
Validierungsfehler messbar machen
Validierungsfehler sind Produkt- und Integrationssignale: Ein Spike kann auf fehlerhafte Client-Releases, Bots oder Missbrauch hinweisen. Metriken wie „Validation errors per endpoint“ und „Top field paths“ helfen bei Priorisierung. In Systemen mit Observability-Stack kann außerdem die Korrelation mit Traces nützlich sein, ähnlich wie beim Ansatz in Distributed Tracing im Backend.
Sicherheit: Validierung ist kein Ersatz für Schutzmechanismen
Schema-Validation reduziert Angriffsfläche, weil unerwartete Strukturen abgewiesen werden und Parser weniger „Überraschungen“ sehen. Trotzdem ersetzt sie keine Authentifizierung, Autorisierung, Rate Limits oder sichere Deserialisierung. Besonders wichtig: Limits für Body-Größe, Timeouts und eine saubere Behandlung von Parser-Fehlern, bevor überhaupt Schema-Validation greift.
Wenn Validierung als Vertragspflege verstanden wird, profitieren Implementierung, Tests und Betrieb gleichermaßen. Das Ergebnis sind APIs, die schneller „Nein“ sagen, wenn etwas nicht passt – und dadurch stabiler „Ja“ liefern, wenn es darauf ankommt.
