Validation de formulaire alignée sur l’API pour arrêter les mauvaises données à la source

Pourquoi des règles de validation décalées provoquent des échecs évitables

Les mauvaises données ne sont généralement pas dramatiques. Ce sont des choses du quotidien : un champ requis laissé vide, une date saisie « 12/13/24 » alors que l’API attend « 2024-12-13 », un numéro de téléphone contenant des lettres, ou une option de menu qui a changé sur le backend mais pas dans le formulaire.

Quand le formulaire accepte ces saisies et que seule l’API les rejette après l’envoi, l’utilisateur se sent trompé. Il a fait le travail, cliqué sur le bouton, puis obtenu un vague « Une erreur est survenue. » Parfois l’erreur apparaît loin du champ à l’origine du problème, et il doit deviner.

Des règles décalées laissent passer quelques problèmes prévisibles : champs requis vides ou ne contenant que des espaces, formats incorrects (email, date, code postal), valeurs hors limites (trop longues, trop courtes, trop d’éléments), valeurs d’enum obsolètes (ancien nom d’offre ou rôle supprimé), et conflits entre champs comme une date de fin antérieure à la date de début.

Le coût s’accumule vite. Chaque requête rejetée peut signifier un abandon d’inscription, un paiement perdu, ou un enregistrement inachevé qui demande nettoyage. Les tickets support suivent : « Je ne peux pas créer de compte », alors que le vrai problème est une simple règle de format. Avec le temps, des enregistrements incohérents s’infiltrent dans la base et pénalisent le reporting et les automatisations.

La validation alignée sur l’API est une idée simple : les mêmes règles s’exécutent des deux côtés. Le formulaire empêche les saisies manifestement incorrectes et affiche un retour clair au niveau du champ avant l’envoi. L’API valide toujours tout (ne faites jamais confiance au navigateur), mais elle confirme principalement ce que l’utilisateur a déjà corrigé.

Validation client vs serveur en clair

La validation côté client se produit dans le navigateur pendant que quelqu’un complète un formulaire. C’est le retour rapide qui détecte tôt les erreurs évidentes : champs requis manquants, un email qui ne ressemble pas à un email, ou un mot de passe trop court.

La validation côté serveur intervient après l’envoi, quand votre API reçoit les données. C’est le dernier rempart qui protège votre base et vos utilisateurs.

Pourquoi il vous faut les deux

Les règles côté client servent la rapidité et la clarté. Elles réduisent la frustration parce que les gens peuvent corriger les problèmes immédiatement.

Les règles côté serveur servent la sécurité et la vérité. Le serveur doit valider car n’importe qui peut contourner le navigateur (scripts personnalisés, requêtes modifiées, vieilles versions d’app), le serveur voit l’état réel (comptes existants, permissions, limites de débit), et certaines vérifications nécessitent des données de confiance (propriété, sécurité, contraintes d’intégrité).

Une idée reçue est de penser que la validation côté client « empêche les mauvaises données ». Elle aide, mais ne peut pas le garantir. Seule l’API peut l’assurer.

L’objectif réel : un seul livre de règles partagé

Ce que vous voulez, c’est un livre de règles partagé : client et serveur appliquent les mêmes exigences, donc l’utilisateur obtient les mêmes réponses aux deux endroits.

Concrètement, cela signifie choisir une source de vérité pour les règles (souvent un schéma API ou la couche de validation serveur), puis faire en sorte que le client s’y conforme. Si le serveur exige un mot de passe de 12+ caractères et bloque les mots de passe courants, le formulaire doit indiquer « 12+ caractères » dès le départ. Le contrôle « mot de passe courant » peut être présenté comme un indice plus doux, mais l’exigence stricte doit être cohérente.

Que valider et où

Certaines vérifications appartiennent au navigateur parce qu’elles aident l’utilisateur à remplir le formulaire. D’autres doivent se faire côté serveur car seul le serveur connaît la vérité du moment. Le but est la cohérence : l’utilisateur doit apprendre les problèmes avant qu’une requête ne faille, et quand le serveur rejette quelque chose, la raison doit correspondre à ce que l’UI enseigne déjà.

Commencez par les règles de forme. Ces bases doivent correspondre partout :

• Si un champ est requis ou non
• Le type attendu (texte, nombre, date)
• Le format attendu par l’API

Si votre API attend un nombre et que le formulaire envoie du texte, la requête échoue même si l’UI semblait correcte.

Les contraintes doivent aussi être partagées : longueur minimale et maximale, valeurs autorisées (liste de codes pays), et motifs simples (par exemple « doit inclure un @ »). La validation côté client donne un retour rapide ; la validation serveur le confirme.

Les règles cross-field demandent plus d’attention car elles impliquent plusieurs champs. Si l’utilisateur peut corriger le problème en comparant deux champs sur le même écran, validez-le dans le formulaire et revérifiez côté serveur. Deux exemples courants : « mot de passe et confirmation doivent correspondre » et « date de début avant date de fin ».

Certaines règles sont exclusivement backend car le client ne peut pas les vérifier de façon fiable. Cela inclut les vérifications d’unicité (cet email est-il déjà enregistré ?), les permissions (cet utilisateur a-t-il le droit de définir cette valeur ?), les limites de débit, tout ce qui dépend de l’état actuel de la base, et les règles de sécurité (rejeter des champs ou valeurs inattendus).

Un formulaire d’inscription peut valider le format d’email localement, mais seule l’API peut confirmer que l’email n’est pas déjà utilisé.

Comment les règles se désalignent

La dérive de validation commence souvent avec de bonnes intentions : quelqu’un corrige vite un bug, publie, et passe à autre chose. Une semaine plus tard, une autre personne ajoute une règle « temporaire » dans un autre fichier. Après quelques itérations, l’UI et l’API ne s’accordent plus, et les utilisateurs subissent des échecs confus.

Le copier-coller de validations est une cause fréquente. Une équipe crée trois formulaires qui collectent le même champ (email, téléphone, nom d’entreprise), mais chaque formulaire finit avec des règles légèrement différentes. L’API peut exiger un format plus strict tandis qu’un formulaire se contente de vérifier « non vide ».

Les changements de version sont une autre source. Le backend met à jour une règle (longueur de mot de passe de 8 à 12, ou un champ devient requis), mais l’UI reste sur l’ancienne hypothèse. Les utilisateurs passent la validation côté client et reçoivent quand même une erreur serveur.

Les différences d’environnement peuvent masquer la dérive jusqu’à ce que ça casse. Staging peut avoir des paramètres assouplis, des feature flags différents, ou une config d’auth différente. Tout semble correct en test, puis la production rejette de vraies saisies parce que les règles sont plus strictes.

Le code généré par IA peut aggraver cela en dupliquant la validation dans plusieurs composants, mélangeant des bibliothèques, ou inventant des regex qui ne correspondent pas à l’API. Il est courant de voir le même champ validé de trois manières différentes dans une même app.

Vous avez probablement une dérive si vous observez des motifs comme :

• Les utilisateurs signalent « c’est OK, puis ça échoue » après Soumettre
• Le même champ se comporte différemment sur différentes pages
• Les erreurs apparaissent comme un générique « Une erreur est survenue »
• Des corrections sont faites dans l’UI sans mettre à jour le contrat API (ou inversement)

Étapes concrètes : faire de l’API la source de vérité

Si les utilisateurs peuvent remplir un formulaire que votre API rejettera, vous accumulez des requêtes inutiles et des échecs confus. La réparation est simple : traitez le contrat API comme la source de vérité, puis faites en sorte que l’UI le reflète.

Commencez par écrire le contrat pour l’endpoint que vous appelez. Pour chaque champ, notez :

• Le type
• Obligatoire vs optionnel
• Plages et limites autorisées
• Formats (email, UUID, date)
• Contraintes comme longueur max ou valeurs autorisées

Puis séparez les règles en deux catégories. D’abord, les règles que le navigateur peut vérifier instantanément (required, format, longueur). Ensuite, les règles que seul le serveur peut connaître (unicité, permissions, limites de débit, « mot de passe actuel correspond »). Cela garde le retour rapide sans prétendre que le client peut garantir la réalité serveur.

Un chemin pratique et durable :

1. Choisissez un format de schéma réutilisable (OpenAPI, JSON Schema, ou une librairie de validation partagée).
2. Placez les règles de requête et de réponse de l’endpoint dans ce schéma, y compris les contraintes.
3. Générez ou réutilisez des validateurs client à partir du schéma pour éviter la copie manuelle.
4. Validez côté serveur en utilisant le même schéma (ou des règles équivalentes) avant la logique métier.
5. Standardisez les codes d’erreur et les modèles de message afin que le même problème apparaisse de la même façon partout.

Rendez aussi les erreurs prévisibles. Utilisez des codes d’erreur stables (comme email_taken ou password_too_short) et laissez client et serveur les mapper vers un texte clair.

Concevoir des messages d’erreur exploitables

Les gens corrigent plus vite quand le message leur dit exactement quoi changer. L’objectif est la cohérence : la même règle doit produire le même message, qu’elle soit détectée dans le navigateur ou rejetée par l’API.

Rédigez une phrase claire par règle et gardez-la stable. Si la règle change, mettez à jour le message en même temps. « Le mot de passe doit comporter au moins 12 caractères » est exploitable. « Entrée invalide » ne l’est pas.

Le placement des erreurs compte autant que le contenu. Placez le message à côté du champ concerné. Ajoutez un court résumé en haut seulement si cela aide à repérer les champs manquants, surtout sur les formulaires longs.

Un schéma fiable pour la plupart des formulaires :

• Un message inline sous le champ (court et spécifique)
• Un style qui met en évidence l’entrée exacte
• Un résumé en haut listant 1 à 3 problèmes (pas de doublons)
• Le focus qui se déplace sur la première erreur après l’envoi

Les erreurs serveur demandent une attention particulière. Même avec de bonnes vérifications côté client, les requêtes échoueront pour des raisons hors du contrôle du client : sessions expirées, conditions de course, ou règles inconnues de l’UI. Quand l’API renvoie des erreurs, mappez-les aux champs à l’aide de clés cohérentes et réutilisez le même libellé. Si une erreur ne concerne pas un seul champ, affichez-la en haut de la page.

Évitez le langage technique côté utilisateur. Les gens ne doivent pas voir « 400 Bad Request » ou des codes bruts. Traduisez-les en phrases simples comme « Cette adresse email est déjà utilisée » ou « Veuillez entrer une date valide ».

Règles cross-field et vérifs asynchrones sans embrouiller l’utilisateur

Certaines validations ne concernent pas un champ isolé mais la façon dont plusieurs champs interagissent. Si vous ne validez chaque champ qu’individuellement, l’utilisateur peut quand même soumettre des données qui échouent côté serveur, produisant une erreur qui semble aléatoire.

La validation cross-field couvre ce que l’utilisateur attend : « la date de fin doit être après la date de début » ou « mot de passe et confirmation identiques ». Règle générale : si l’utilisateur peut corriger en comparant les champs sur le même écran, validez-le dans le formulaire et expliquez-le juste à côté des champs.

Gardez le message lié au correctif. « Dates invalides » est vague. « La date de fin doit être postérieure à la date de début » indique clairement quoi changer.

Vérifications asynchrones : quand interroger le serveur

Certaines vérifications dépendent de données en direct ou de permissions, donc requièrent le serveur. Exemples : « email déjà utilisé », « code d’invitation valide », ou « nom d’utilisateur disponible ». Ces vérifs font toujours partie d’un système de validation aligné, mais l’UI doit les gérer avec douceur pour ne pas interrompre la saisie.

Une approche simple :

• Affichez un petit état « Vérification… » après que l’utilisateur fait une pause ou quitte le champ.
• Laissez l’utilisateur continuer à remplir le formulaire pendant la vérification.
• Si la vérif échoue, expliquez la marche à suivre (utiliser un autre email, demander un nouvel invite).
• Si la vérif ne peut pas s’exécuter (hors ligne ou timeout), ne prétendez pas qu’elle a réussi. Demandez de réessayer à l’envoi.

Quand valider : à la frappe, au blur, ou progressivement

Le timing compte. Valider à chaque frappe peut donner l’impression que le formulaire chipote avec l’utilisateur.

Un défaut simple qui marche souvent :

• Validez format de base et longueur minimale pendant la frappe.
• Validez les règles cross-field quand le second champ est touché (confirmation) ou au blur.
• Lancez les vérifs asynchrones au blur ou après une courte pause, pas à chaque caractère.
• Revérifiez tout à l’envoi et mappez les erreurs serveur aux bons champs.

Erreurs courantes qui créent du bruit

Les échecs de validation bruyants semblent aléatoires aux utilisateurs, mais proviennent souvent de quelques erreurs prévisibles. Le thème principal est la dérive : l’UI et l’API commencent lentement à appliquer des règles différentes.

Se fier uniquement aux contrôles côté client est un piège classique. Les utilisateurs peuvent contourner le navigateur, ou votre API peut être appelée depuis un autre client. Quand le serveur devient le premier lieu où la validation échoue, les utilisateurs ne voient l’erreur qu’après avoir rempli le formulaire.

Les motifs qui provoquent le plus de moments « pourquoi ça a échoué ? » :

• Le même champ a des règles différentes selon les écrans (inscription vs paramètres).
• Des regex qui bloquent des saisies réelles, comme des noms avec apostrophes, caractères non anglais, ou numéros d’appartement dans les adresses.
• L’API renvoie une erreur générique 400/500, donc l’UI ne peut pas mettre en évidence le champ à corriger.
• Les règles d’API changent mais les tests UI et les scripts QA attendent l’ancien comportement.
• Les erreurs sont écrites pour les devs (« violation de contrainte ») au lieu des utilisateurs (« Le mot de passe doit comporter au moins 12 caractères. »)

Un exemple simple : l’UI accepte « Sam O’Neil » dans un formulaire de profil, mais l’API le rejette parce que la regex serveur n’autorise que A-Z. L’utilisateur voit « Requête échouée » sans indication du champ, recommence et abandonne.

Réduire le bruit revient souvent à quelques corrections ciblées : standardiser les règles par champ sur tous les écrans, assouplir les patterns pour coller aux saisies réelles, et renvoyer des codes d’erreur par champ que l’UI peut placer exactement où il faut.

Checklist rapide pour vérifier l’alignement avant la mise en production

Avant de livrer, faites une passe rapide qui couvre tout le chemin : ce que l’utilisateur tape, ce que l’UI bloque, ce que l’API rejette, et ce que voit l’utilisateur.

Commencez par comparer les exigences de l’API au formulaire. Si l’API dit qu’un champ est requis, l’UI doit clairement l’indiquer et empêcher un envoi vide. Si l’UI exige quelque chose que l’API n’attend pas, l’utilisateur peut rester bloqué pour rien.

Utilisez un petit jeu de tests répétables par champ :

• Vérifier les règles required : chaque champ requis côté API est requis dans l’UI, et les champs optionnels sont vraiment optionnels.
• Tester trois mauvaises valeurs par champ : trop court, trop long, mauvais format.
• Exécuter une règle cross-field de bout en bout : le message client et serveur doivent être identiques.
• Confirmer que l’API renvoie des erreurs au niveau du champ, pas seulement une chaîne générique.
• Vérifier que l’UI traite différemment les erreurs réseau et les erreurs de validation (un timeout ne doit pas ressembler à « votre email est invalide »).

Un conseil pratique : faites au moins un test de soumission réel avec les outils dev du navigateur ouverts. Si le serveur rejette quelque chose que l’UI a autorisé, vous avez de la dérive.

Exemple réaliste : un formulaire d’inscription qui échoue sans cesse

Une équipe publie une page d’inscription avec quatre champs : email, mot de passe, nom de l’entreprise et code d’invitation. Tout marche visuellement. Mais le support reçoit des tickets : « Ça dit qu’il y a une erreur. »

La cause racine est un décalage. L’UI vérifie que le mot de passe fait au moins 8 caractères. L’API exige 12. Un utilisateur tape Sunshine1 (9 caractères), le formulaire affiche une coche verte, la requête part, et l’API la rejette avec un 400. L’app transforme ça en une bannière générique en haut, et l’utilisateur ne sait pas quoi corriger.

Les symptômes sont faciles à repérer :

• Beaucoup de requêtes échouées juste après la soumission
• Bannières d’erreur génériques au lieu d’indices au niveau des champs
• Utilisateurs qui réessaient avec les mêmes données et restent bloqués

La correction n’est pas « ajouter plus de contrôles ». C’est faire du contrat API la source de vérité et générer les règles client à partir de celui-ci.

Un flux de réparation simple :

1. Décidez la règle réelle (8 ou 12) avec l’équipe qui possède l’API.
2. Mettez à jour le contrat API (par exemple un schéma OpenAPI) pour refléter la règle.
3. Régénérez ou mettez à jour la validation client à partir du contrat.
4. Mappez l’erreur API au champ mot de passe avec un message clair comme « Le mot de passe doit comporter au moins 12 caractères. »
5. Retestez le flux, y compris un mot de passe trop court et un code d’invitation invalide.

Après cela, les requêtes invalides diminuent car les utilisateurs reçoivent un retour avant l’envoi. Si le code d’invitation doit être vérifié sur le serveur, l’UI peut quand même aider : valider localement le format (longueur, caractères autorisés), puis afficher « Code d’invitation introuvable » seulement après confirmation serveur.

Étapes suivantes pour maintenir l’alignement dans le temps

Choisissez un formulaire à fort trafic comme pilote d’alignement. Prenez quelque chose qui casse souvent ou qui a un impact sur le chiffre d’affaires (inscription, checkout, réinitialisation de mot de passe). Mettez côte à côte les règles API (types, champs requis, longueurs min/max, valeurs autorisées) et les règles du formulaire et comblez les écarts jusqu’à ce que les mêmes saisies passent ou échouent aux deux endroits.

Une fois qu’un formulaire est propre, appliquez la même méthode au suivant plutôt que d’essayer de tout corriger d’un coup. Les petites victoires sont plus faciles à vérifier et réduisent rapidement les tickets support.

Ajouter une revue légère du contrat quand l’API change

La dérive survient quand l’API évolue et que l’UI ne suit pas. Ajoutez une étape à votre processus de changement : à chaque modification de requête ou de réponse, quelqu’un vérifie si les règles de formulaire et les messages d’erreur correspondent toujours.

Gardez la routine courte :

• Notez quelles saisies sont devenues plus strictes ou plus laxistes.
• Mettez à jour les règles serveur et client dans la même pull request.
• Confirmez que les messages d’erreur correspondent aux noms de champs visibles dans le formulaire.
• Exécutez un test de mauvaise entrée volontaire (champ requis vide, chaîne trop longue, format invalide).

Si la base de code est en désordre, commencez par un audit

Si votre app a été générée par un outil IA ou héritée d’un prototype, la validation décalée est souvent un symptôme de problèmes plus larges : règles dupliquées dans plusieurs fichiers, flux d’auth incomplets, ou patterns dangereux comme la confiance aux contrôles côté client.

Si vous avez besoin d’un examen extérieur, FixMyMess (fixmymess.ai) se concentre sur le diagnostic et la réparation des apps générées par IA, y compris la reconnexion des validations client/serveur, la correction des authentifications cassées, et le renforcement des problèmes de sécurité qui apparaissent quand des prototypes rencontrent du trafic réel.