API-konforme Formularvalidierung — schlechte Daten an der Quelle verhindern

Warum nicht abgestimmte Validierung vermeidbare Fehler verursacht

Schlechte Daten sind selten dramatisch. Es sind alltägliche Dinge: ein Pflichtfeld, das leer bleibt, ein Datum, das als “12/13/24” eingegeben wird, obwohl die API “2024-12-13” erwartet, eine Telefonnummer mit Buchstaben oder eine Dropdown-Option, die auf dem Backend geändert wurde, aber nicht im Formular.

Wenn das Formular diese Eingaben akzeptiert und erst die API sie nach dem Absenden ablehnt, fühlen sich Nutzer hereingelegt. Sie haben gearbeitet, auf den Button geklickt und bekommen dann ein vages „Etwas ist schiefgelaufen.“ Manchmal erscheint der Fehler weit weg vom Feld, das ihn verursacht hat, sodass sie raten müssen.

Nicht übereinstimmende Regeln lassen ein paar vorhersehbare Probleme durchrutschen: leere oder nur aus Leerzeichen bestehende Pflichtfelder, falsche Formate (E-Mail, Datum, Postleitzahl), Werte außerhalb der Grenzen (zu lang, zu kurz, zu viele Elemente), veraltete Enum-Werte (ein alter Tarifname oder entfernte Rolle) und feldübergreifende Konflikte wie ein Enddatum vor dem Startdatum.

Die Kosten summieren sich schnell. Jede fehlgeschlagene Anfrage kann eine abgebrochene Anmeldung, einen verlorenen Checkout oder einen halb angelegten Datensatz bedeuten, der bereinigt werden muss. Support-Tickets folgen: „Ich kann kein Konto erstellen“, obwohl das eigentliche Problem eine einfache Formatregel ist. Mit der Zeit schleichen sich inkonsistente Datensätze in Ihre Datenbank ein und machen Berichte und Automatisierungen weniger zuverlässig.

API-konforme Formularvalidierung ist eine einfache Idee: dieselben Regeln laufen an beiden Stellen. Das Formular verhindert offensichtliche schlechte Eingaben und zeigt klare, feldbezogene Hinweise, bevor die Anfrage rausgeht. Die API validiert weiterhin alles (vertraue niemals dem Browser), bestätigt aber größtenteils nur, was der Nutzer bereits korrigiert hat.

Client- vs. Server-Validierung in einfachen Worten

Client-seitige Validierung passiert im Browser, während jemand ein Formular ausfüllt. Sie gibt schnelles Feedback und fängt offensichtliche Fehler früh ab: fehlende Pflichtfelder, eine E-Mail, die nicht wie eine E-Mail aussieht, oder ein zu kurzes Passwort.

Server-seitige Validierung passiert, nachdem das Formular abgeschickt wurde und Ihre API die Daten erhält. Sie ist das letzte Tor, das Ihre Datenbank und Ihre Nutzer schützt.

Warum Sie beides brauchen

Client-seitige Regeln sorgen für Tempo und Klarheit. Sie reduzieren Frust, weil Menschen Probleme sofort beheben können.

Server-seitige Regeln sorgen für Sicherheit und Wahrheit. Der Server muss validieren, weil jeder den Browser umgehen kann (eigene Skripte, manipulierte Requests, alte App-Versionen), der Server den tatsächlichen Zustand sieht (bestehende Accounts, Berechtigungen, Ratenbegrenzungen) und manche Prüfungen vertrauenswürdige Daten benötigen (Eigentum, Sicherheit, Integritätsbedingungen).

Ein verbreitetes Missverständnis ist zu denken, die Client-Validierung „verhindere schlechte Daten“. Sie hilft, kann es aber nicht garantieren. Nur die API kann dieses Versprechen geben.

Das eigentliche Ziel: ein gemeinsames Regelwerk

Was Sie wollen, ist ein gemeinsames Regelwerk: Client und Server setzen dieselben Anforderungen durch, sodass Nutzer in beiden Fällen dieselbe Antwort bekommen.

In der Praxis bedeutet das, eine Quelle der Wahrheit für Regeln zu wählen (oft ein API-Schema oder eine serverseitige Validierungsschicht) und dann das UI daran auszurichten. Wenn der Server ein Passwort von 12+ Zeichen verlangt und gängige Passwörter blockiert, sollte das Formular von vornherein „12+ Zeichen“ anzeigen. Die Prüfung auf „gängige Passwörter“ kann ein weicherer Hinweis sein, aber die harte Anforderung muss konsistent sein.

Was wo validiert werden sollte

Einige Prüfungen gehören in den Browser, weil sie Menschen beim Ausfüllen helfen. Andere Prüfungen müssen auf dem Server stattfinden, weil nur der Server weiß, was gerade wahr ist. Das Ziel ist Konsistenz: Nutzer sollten Probleme kennen lernen, bevor eine Anfrage fehlschlägt, und wenn der Server etwas ablehnt, sollte der Grund dem entsprechen, was die UI bereits vermittelt.

Beginnen Sie mit Regeln zur Form des Feldes. Diese Basics sollten überall übereinstimmen:

• Ob ein Feld erforderlich ist
• Der erwartete Typ (Text, Zahl, Datum)
• Das Format, das die API erwartet

Wenn Ihre API eine Zahl erwartet und das Formular Text sendet, schlägt die Anfrage fehl, selbst wenn das UI in Ordnung aussah.

Einschränkungen sollten ebenfalls geteilt werden: Mindest- und Höchstlänge, erlaubte Werte (wie eine Länderliste) und einfache Muster (zum Beispiel „muss ein @ enthalten“). Client-seitige Validierung gibt schnelles Feedback; Server-seitige Validierung bestätigt es.

Feldübergreifende Regeln brauchen besondere Aufmerksamkeit, weil sie mehr als eine Eingabe betreffen. Wenn Nutzer das Problem beheben können, indem sie zwei Felder auf derselben Seite vergleichen, validieren Sie es im Formular und prüfen Sie es erneut auf dem Server. Zwei gängige Beispiele sind „Passwort und Passwort bestätigen müssen übereinstimmen“ und „Startdatum muss vor Enddatum liegen“.

Manche Regeln sind Backend-only, weil der Client sie nicht zuverlässig prüfen kann. Dazu gehören Einzigartigkeitsprüfungen (ist diese E-Mail schon registriert?), Berechtigungen (darf dieser Nutzer diesen Wert setzen?), Ratenbegrenzungen, alles, was vom aktuellen Datenbankzustand abhängt, und Sicherheitsregeln (ungewöhnliche Felder oder Werte ablehnen).

Ein Anmeldeformular kann das E-Mail-Format lokal prüfen, aber nur die API kann bestätigen, ob die E-Mail bereits vergeben ist.

Wie Validierungsregeln auseinanderdriften

Validierungsdrift beginnt oft mit guten Absichten: Jemand behebt schnell einen Bug, deployed und macht weiter. Eine Woche später fügt eine andere Person eine „temporäre“ Regel in einer anderen Datei hinzu. Nach ein paar Iterationen stimmen UI und API nicht mehr überein und Nutzer bekommen verwirrende Fehler.

Copy-&-Paste-Validierung ist eine häufige Ursache. Ein Team baut drei Formulare, die dasselbe Feld sammeln (E-Mail, Telefon, Firmenname), aber jedes Formular hat am Ende leicht unterschiedliche Regeln. Die API könnte ein strengeres Format durchsetzen, während ein Formular nur „nicht leer“ prüft.

Versionsänderungen sind eine weitere Quelle. Das Backend aktualisiert eine Regel (Passwortlänge geht von 8 auf 12 oder ein Feld wird Pflicht), aber das UI bleibt bei der älteren Annahme. Nutzer passieren die client-seitige Validierung und stoßen dennoch auf Server-Fehler.

Unterschiede zwischen Umgebungen können Drift verbergen, bis es schiefgeht. Staging kann gelockerte Einstellungen, andere Feature-Flags oder eine andere Auth-Provider-Konfiguration haben. Alles sieht in Tests gut aus, aber Produktion lehnt echte Eingaben ab, weil die Regeln strenger sind.

AI-generierter Code kann das verschlimmern, indem er Validierung über Komponenten dupliziert, Bibliotheken mischt oder reguläre Ausdrücke erfindet, die nicht zur API passen. Es ist üblich, dass dasselbe Feld in einer App dreimal unterschiedlich validiert wird.

Sie haben wahrscheinlich Drift, wenn Sie Muster wie diese sehen:

• Nutzer melden „es sagt OK, dann schlägt es fehl“ nach dem Drücken von Submit
• Dasselbe Feld verhält sich auf verschiedenen Seiten unterschiedlich
• Fehler treten als generisches „Etwas ist schiefgelaufen“ auf
• Fixes werden im UI vorgenommen, ohne den API-Vertrag zu aktualisieren (oder umgekehrt)

Schritt-für-Schritt: Machen Sie die API zur Quelle der Wahrheit

Wenn Nutzer ein Formular ausfüllen können, das Ihre API ablehnen wird, haben Sie verschwendete Anfragen und verwirrende Fehler. Die Lösung ist geradlinig: Behandeln Sie den API-Vertrag als Quelle der Wahrheit und lassen Sie das UI ihn spiegeln.

Starten Sie, indem Sie den Vertrag für den Endpoint, den Sie aufrufen, aufschreiben. Erfassen Sie für jedes Feld:

• Typ
• Pflicht vs. optional
• Erlaubte Bereiche und Grenzen
• Formate (E-Mail, UUID, Datum)
• Einschränkungen wie Max-Länge oder erlaubte Werte

Teilen Sie die Regeln dann in zwei Buckets. Zuerst Regeln, die der Browser sofort prüfen kann (Pflicht, Format, Länge). Zweitens Regeln, die nur der Server kennen kann (Einzigartigkeit, Berechtigungen, Ratenbegrenzungen, „aktuelles Passwort stimmt überein“). So bleibt das Feedback schnell, ohne vorzugeben, dass der Client die Server-Realität garantieren kann.

Ein praktischer Pfad, der langfristig hält:

1. Wählen Sie ein Schema-Format, das Sie wiederverwenden können (OpenAPI, JSON Schema oder eine gemeinsame Validierungsbibliothek).
2. Legen Sie die Request- und Response-Regeln des Endpoints in diesem Schema fest, inklusive Einschränkungen.
3. Generieren oder verwenden Sie Client-Validatoren aus dem Schema, damit UI-Regeln nicht per Hand kopiert werden.
4. Validieren Sie serverseitig mit demselben Schema (oder äquivalenten Regeln), bevor die Business-Logik läuft.
5. Standardisieren Sie Fehlercodes und Nachrichtenvorlagen, damit dasselbe Problem überall gleich aussieht.

Machen Sie Fehler vorhersehbar. Verwenden Sie stabile Fehlercodes (wie email_taken oder password_too_short) und lassen Sie sowohl Client als auch Server diese in klare Texte übersetzen.

Fehlermeldungen designen, die Nutzer umsetzen können

Menschen beheben Probleme schneller, wenn die Meldung genau sagt, was zu ändern ist. Das Ziel ist Konsistenz: dieselbe Regel sollte dieselbe Meldung erzeugen, egal ob sie im Browser gefangen oder von der API zurückgegeben wurde.

Formulieren Sie pro Regel einen klaren Satz und halten Sie ihn stabil. Wenn sich die Regel ändert, aktualisieren Sie die Meldung gleichzeitig. „Passwort muss mindestens 12 Zeichen lang sein“ ist umsetzbar. „Ungültige Eingabe“ ist es nicht.

Wo Sie Fehler anzeigen, ist genauso wichtig wie was Sie sagen. Platzieren Sie die Meldung neben dem Feld, das Aufmerksamkeit benötigt. Fügen Sie eine kurze Zusammenfassung oben nur dann hinzu, wenn sie hilft, fehlende Felder zu finden — besonders bei langen Formularen.

Ein verlässliches Muster für die meisten Formulare ist:

• Eine Inline-Meldung unter dem Feld (kurz und spezifisch)
• Styling, das die genaue Eingabe hervorhebt
• Eine Top-Zusammenfassung mit 1–3 Problemen (keine Duplikate)
• Fokus auf den ersten Fehler nach dem Absenden

Server-Fehler brauchen besondere Sorgfalt. Auch mit guten Client-Prüfungen werden Anfragen aus Gründen scheitern, die der Client nicht komplett kontrollieren kann: abgelaufene Sessions, Race-Conditions oder Regeln, die das UI noch nicht kannte. Wenn die API mit Fehlern antwortet, mappen Sie diese zurück auf Felder mit konsistenten Schlüsseln und verwenden Sie dieselbe Formulierung wieder. Wenn ein Fehler keinem einzelnen Feld zugeordnet ist, zeigen Sie ihn als Seiten-Nachricht an.

Vermeiden Sie technisches Vokabular in nutzergerichtetem Text. Menschen sollten nicht „400 Bad Request“ oder rohe Validierungscodes sehen. Übersetzen Sie sie in klare Sprache wie „Diese E-Mail-Adresse wird bereits verwendet“ oder „Bitte geben Sie ein gültiges Datum ein."

Feldübergreifende und asynchrone Prüfungen ohne Verwirrung

Manche Validierungen betreffen nicht nur ein Feld, sondern dessen Zusammenspiel. Wenn Sie nur jede Eingabe isoliert prüfen, können Nutzer trotzdem Daten absenden, die auf dem Server fehlschlagen und dann zufällig wirken.

Feldübergreifende Validierung deckt Prüfungen ab, die Nutzer erwarten: „Enddatum muss nach Startdatum liegen“ oder „Passwort und Passwort bestätigen müssen übereinstimmen.“ Faustregel: Wenn der Nutzer es beheben kann, indem er Felder auf derselben Seite vergleicht, validieren Sie es im Formular und erklären Sie es direkt neben den Feldern.

Halten Sie die Meldung an die Lösung gebunden. „Daten sind ungültig“ ist vage. „Enddatum muss nach Startdatum liegen“ sagt ihnen, was zu ändern ist.

Asynchrone Prüfungen: wenn Sie den Server fragen müssen

Manche Prüfungen hängen von echten Daten oder Berechtigungen ab und erfordern daher den Server. Häufige Beispiele sind „E-Mail bereits verwendet“, „Invite-Code ist gültig“ oder „Benutzername verfügbar“. Diese Prüfungen gehören trotzdem in ein abgestimmtes Validierungssystem, aber das UI muss sie sanft handhaben, damit sie das Tippen nicht unterbrechen.

Ein einfacher Ansatz:

• Zeigen Sie einen kleinen „Prüfe…“-Zustand, nachdem der Nutzer pausiert hat oder das Feld verlässt.
• Lassen Sie den Nutzer das Formular weiter ausfüllen, während die Prüfung läuft.
• Wenn die Prüfung fehlschlägt, erklären Sie, was als Nächstes zu tun ist (andere E-Mail verwenden, neuen Invite anfordern).
• Wenn die Prüfung nicht laufen kann (offline oder Timeout), tun Sie nicht so, als wäre sie bestanden. Bitten Sie um einen Retry beim Absenden.

Wann prüfen: bei Blur, Submit oder progressiv

Timing ist wichtig. Bei jedem Tastendruck zu validieren kann sich anfühlen, als würde das Formular mit dem Nutzer streiten.

Eine einfache Standard-Empfehlung, die für viele Teams funktioniert:

• Prüfen Sie grundlegendes Format und Mindestlänge während des Tippens.
• Prüfen Sie feldübergreifende Regeln, wenn das zweite Feld berührt wird (Passwort bestätigen) oder beim Blur.
• Führen Sie asynchrone Prüfungen beim Blur oder nach kurzer Pause aus, nicht bei jedem Tastendruck.
• Überprüfen Sie alles erneut beim Absenden und mappen Sie Server-Fehler auf die richtigen Felder.

Häufige Fehler, die laute Fehlschläge erzeugen

Laute Validierungsfehler wirken zufällig für Nutzer, stammen aber meist aus einigen vorhersehbaren Fehlern. Das größte Thema ist Drift: UI und API beginnen langsam, unterschiedliche Regeln durchzusetzen.

Auf Client-only-Prüfungen zu vertrauen ist eine klassische Falle. Nutzer können den Browser umgehen oder Ihre API kann von einem anderen Client aufgerufen werden. Wenn die Server-Validierung die erste Stelle wird, an der geprüft wird, sehen Menschen Fehler erst, nachdem sie viel Zeit ins Formular investiert haben.

Muster, die die meisten „warum ist das fehlgeschlagen?“-Momente verursachen, sind:

• Dasselbe Feld hat unterschiedliche Regeln auf verschiedenen Bildschirmen (Signup vs. Einstellungen).
• Regex-Regeln, die reale Eingaben blockieren, wie Namen mit Apostrophen, nicht-englische Zeichen oder Wohnungsnummern in Adressen.
• Die API liefert einen generischen 400/500-Fehler, sodass das UI nicht hervorheben kann, welches Feld zu korrigieren ist.
• API-Validierungsregeln ändern sich, aber UI-Tests und QA-Skripte erwarten noch das alte Verhalten.
• Fehler sind für Entwickler geschrieben („constraint violation“) statt für Nutzer („Passwort muss mindestens 12 Zeichen haben").

Ein einfaches Beispiel: Das UI akzeptiert „Sam O’Neil“ in einem Profilformular, aber die API lehnt ab, weil die Server-Regex nur A–Z zulässt. Der Nutzer sieht „Anfrage fehlgeschlagen“ ohne Feld-Hervorhebung, versucht es erneut und gibt auf.

Rauschen zu reduzieren heißt oft, sich auf wenige gezielte Fixes zu konzentrieren: Regeln pro Feld über Bildschirme standardisieren, Muster lockern, um reale Eingaben abzudecken, und feldspezifische Fehlercodes zurückgeben, die das UI genau dort platzieren kann, wo Nutzer sie brauchen.

Schnell-Checkliste zur Überprüfung der Übereinstimmung vor dem Release

Vor dem Shipping machen Sie eine kurze Prüfung des kompletten Pfads: was der Nutzer tippt, was das UI blockiert, was die API ablehnt und welche Meldung der Nutzer sieht.

Vergleichen Sie die API-Anforderungen mit dem Formular. Wenn die API sagt, ein Feld ist erforderlich, sollte das UI es deutlich als Pflicht markieren und ein leeres Absenden verhindern. Wenn das UI etwas verlangt, das die API nicht verlangt, können Nutzer unnötig feststecken.

Nutzen Sie eine kleine, wiederholbare Testmenge pro Feld:

• Pflicht-Regeln abgleichen: Jedes Pflichtfeld der API ist Pflicht im UI, optionale Felder sind wirklich optional.
• Probieren Sie drei schlechte Werte pro Feld: zu kurz, zu lang, falsches Format.
• Führen Sie eine feldübergreifende Regel Ende-zu-Ende durch: die Client- und Server-Meldung sollten dasselbe sagen.
• Bestätigen Sie, dass die API feldbezogene Fehler zurückgibt, nicht nur eine einzige generische Zeichenkette.
• Bestätigen Sie, dass das UI Netzwerkfehler anders behandelt als Validierungsfehler (ein Timeout sollte nicht wie „Ihre E-Mail ist ungültig“ aussehen).

Ein praktischer Tipp: Machen Sie mindestens einen echten Submit-Test mit geöffneten Browser-Dev-Tools. Wenn der Server etwas ablehnt, das das UI erlaubt hat, haben Sie Drift.

Ein realistisches Beispiel: Ein Anmeldeformular, das immer wieder fehlschlägt

Ein Team releast eine Signup-Seite mit vier Feldern: E-Mail, Passwort, Firmenname und Invite-Code. Im Browser sieht alles gut aus. Trotzdem stapeln sich Support-Tickets: „Es sagt immer, dass etwas schiefgelaufen ist."

Die Ursache ist eine Fehlanpassung. Das UI prüft, dass das Passwort mindestens 8 Zeichen hat. Die API verlangt mindestens 12. Ein Nutzer tippt Sunshine1 (9 Zeichen), das Formular zeigt ein grünes Häkchen, die Anfrage wird abgeschickt und die API lehnt mit einem 400-Response ab. Die App verwandelt das in ein generisches Banner oben und der Nutzer weiß nicht, was zu tun ist.

Symptome sind leicht zu erkennen:

• Viele fehlgeschlagene Anfragen direkt nach dem Absenden
• Generische Fehlermeldungen statt feldbezogener Hinweise
• Nutzer versuchen es immer wieder mit denselben Daten und stecken fest

Die Lösung ist nicht „mehr Checks hinzufügen“. Die API-Vertrag sollte die Quelle der Wahrheit sein und Client-Regeln sollten daraus generiert werden.

Ein einfacher Reparatur-Flow:

1. Entscheiden Sie mit dem API-Team die echte Regel (8 oder 12).
2. Aktualisieren Sie den API-Vertrag (z. B. ein OpenAPI-Schema), damit er die Regel widerspiegelt.
3. Regenerieren oder aktualisieren Sie die Client-Validierung aus dem Vertrag.
4. Mappen Sie den API-Fehler auf das Passwortfeld mit einer klaren Meldung wie „Passwort muss mindestens 12 Zeichen lang sein.“
5. Testen Sie den Flow erneut, inklusive eines zu kurzen Passworts und eines ungültigen Invite-Codes.

Danach sinken fehlgeschlagene Anfragen, weil Nutzer Feedback vor dem Absenden erhalten. Wenn der Invite-Code serverseitig geprüft werden muss, kann das UI trotzdem helfen: prüfen Sie das Format lokal (Länge, erlaubte Zeichen) und zeigen Sie „Invite-Code nicht gefunden“ erst, nachdem der Server es bestätigt hat.

Nächste Schritte, um Validierung langfristig in Einklang zu halten

Wählen Sie ein stark frequentiertes Formular als Pilot zur Abstimmung. Nehmen Sie etwas, das oft bricht oder am meisten Umsatz beeinflusst, wie Signup, Checkout oder Passwort-Reset. Legen Sie die API-Regeln (Typen, Pflichtfelder, Min-/Max-Längen, erlaubte Werte) neben die Formularregeln und schließen Sie die Lücken, bis dieselben Eingaben an beiden Stellen bestehen oder fehlschlagen.

Wenn ein Formular sauber funktioniert, wiederholen Sie die Methode mit dem nächsten Formular, anstatt alles auf einmal zu reparieren. Kleine Erfolge sind leichter zu verifizieren und reduzieren Support-Tickets schnell.

Fügen Sie eine leichte Vertragsprüfung bei API-Änderungen hinzu

Validation drift entsteht, wenn die API sich weiterentwickelt und das UI nicht. Fügen Sie einen Schritt in Ihren normalen Änderungsprozess: Wann immer sich die Form eines API-Requests oder -Responses ändert, prüft jemand, ob die Formularregeln und Fehlermeldungen noch passen.

Halten Sie die Routine kurz:

• Notieren Sie, welche Eingaben strenger oder lockerer wurden.
• Aktualisieren Sie Server- und Client-Regeln in demselben Pull Request.
• Bestätigen Sie, dass Fehlermeldungen die Feldnamen verwenden, wie sie im Formular auftauchen.
• Führen Sie absichtlich einen Bad-Input-Test durch (leeres Pflichtfeld, zu langer String, ungültiges Format).

Wenn der Codebestand chaotisch ist: mit einem Audit beginnen

Wenn Ihre App von einem AI-Tool generiert wurde oder Sie einen Prototyp geerbt haben, ist mismatched Validation oft ein Symptom größerer Probleme: duplizierte Regeln in mehreren Dateien, halbfertige Auth-Flows oder unsichere Muster wie das Vertrauen auf client-only-Prüfungen.

Wenn Sie eine externe Prüfung brauchen, konzentriert sich FixMyMess (fixmymess.ai) darauf, AI-generierte Apps zu diagnostizieren und zu reparieren — einschließlich dem Wiederverbinden von Client- und Server-Validierung, dem Beheben gebrochener Authentifizierung und dem Härten von Sicherheitsproblemen, die auftreten, wenn Prototypen echten Traffic erreichen.