Tests de contrat pour API : éviter les changements cassants dans les équipes rapides

Pourquoi les changements cassants d'API se retrouvent encore dans les releases

La plupart des équipes finissent par avoir une API qui sert de nombreux clients : une application web, une app iOS, une app Android, et parfois des outils internes. Même si tout le monde parle des mêmes endpoints, chaque client utilise l'API d'une façon légèrement différente. Un écran peut s'attendre à ce qu'un champ existe toujours, alors qu'un autre ne l'utilise que lorsqu'un filtre est appliqué.

Le vrai problème apparaît quand ces parties sont livrées à des rythmes différents. Le backend peut être déployé plusieurs fois par jour, le web se déploie rapidement, et les releases mobiles avancent plus lentement à cause des validations et des déploiements progressifs. Cet écart crée des ruptures surprises : l'API est mise à jour pour le client le plus récent, mais la version mobile publiée hier est encore en circulation et reçoit maintenant des réponses qu'elle ne sait pas traiter.

Quand cela arrive, les symptômes ne sont pas subtils :

• Un écran qui devient soudainement vide parce qu'un champ a été renommé ou déplacé
• Des plantages causés par des null inattendus ou des objets manquants
• Des tickets de support « Quelque chose est cassé » difficiles à reproduire
• Un pic d'erreurs dans les logs juste après un déploiement backend
• Des releases de hotfix qui ajoutent du code défensif au lieu de corriger la cause

Les tests manuels et la QA manquent souvent ces problèmes parce que les cas à risque ne sont pas dans le happy path. Un testeur peut vérifier que « Créer une commande » fonctionne, mais pas essayer une ancienne version de l'app, un profil partiellement rempli, un rôle d'utilisateur rare, ou une réponse où une liste est vide. Ajoutez du caching, des feature flags et des déploiements progressifs, et vous obtenez encore plus de combinaisons qu'un plan de test ne peut couvrir.

Un exemple typique : le backend remplace status: "approved" par status: { code: "approved" } pour gérer la localisation. L'app web est mise à jour le même jour et fonctionne. Mais la version iOS en production attend toujours une chaîne, échoue à parser la réponse et les utilisateurs voient une page blanche après la connexion.

C'est pourquoi les tests de contrat pour les API existent : pas pour remplacer la QA, mais pour attraper ces changements « ça marche pour mon client le plus récent » avant qu'ils n'atteignent la production.

Qu'est-ce que le test de contrat (et ce que ce n'est pas)

Le test de contrat est une façon pour un consommateur d'API (app web, mobile ou un autre service) et un fournisseur d'API (votre backend) de s'accorder sur la manière dont ils vont communiquer. Cet accord est le contrat. Un test de contrat vérifie une chose simple : le fournisseur se comporte-t-il toujours comme le consommateur s'y attend, même après des changements ?

Dans la pratique, les tests de contrat se situent entre les tests unitaires et les tests end-to-end. Les tests unitaires sont rapides et locaux, mais ils peuvent manquer des désaccords entre équipes parce qu'ils testent du code interne, pas la frontière partagée. Les tests end-to-end exercent des flux réels à travers plusieurs systèmes, mais ils sont plus lents, plus coûteux à maintenir, et échouent souvent pour des raisons sans rapport avec un changement d'API (données de test, timing UI, environnements instables).

Un contrat n'est pas un énorme document. C'est une description ciblée des requêtes qu'un consommateur enverra et des réponses qu'il doit recevoir. Un bon contrat couvre généralement :

• Endpoints et méthodes (par exemple, POST /orders)
• Champs requis et optionnels, incluant les types et règles de base
• Codes de statut et forme des réponses d'erreur (à quoi ressemble un 400 vs 404)
• En-têtes et attentes d'auth (token présent, content-type)
• Valeurs par défaut importantes et règles de compatibilité (que se passe-t-il si un champ est manquant)

Voici un simple exemple du genre de cassure qu'un test de contrat détecte tôt : le backend renomme total_price en totalPrice. Les tests unitaires peuvent continuer de passer. Les tests end-to-end peuvent ne pas couvrir cet écran ou échouer d'une manière confuse. Un test de contrat échoue immédiatement et indique le désaccord exact.

Il est utile de clarifier ce que les tests de contrat ne font pas. Ils ne remplacent pas les tests de performance, de sécurité, ou les tests complets de parcours utilisateur. Ils ne détecteront pas non plus tous les bugs logiques. En revanche, ils réduisent le risque de release le plus courant dans les équipes rapides : un changement « mineur » de l'API qui casse silencieusement un client.

Si votre backend est généré ou change fréquemment (par exemple lorsque vous régénérez des APIs sur une plateforme comme AppMaster), les tests de contrat sont un filet de sécurité pratique car ils vérifient que les attentes des clients tiennent toujours après chaque changement.

Choisir une approche de contrat pour les équipes web et mobile

Quand le web et le mobile sont fréquemment publiés, la difficulté n'est pas « tester l'API ». C'est s'accorder sur ce qui ne doit pas changer pour chaque client. C'est là que les tests de contrat aident, mais il faut choisir qui possède le contrat.

Option 1 : contrats pilotés par le consommateur (CDC)

Avec les contrats pilotés par le consommateur, chaque client (web, iOS, Android, intégration partenaire) définit ce dont il a besoin de l'API. Le fournisseur prouve ensuite qu'il peut satisfaire ces attentes.

Cela fonctionne bien quand les clients évoluent indépendamment, car le contrat reflète l'utilisation réelle, pas ce que l'équipe backend pense être utilisé. C'est aussi adapté à la réalité multi-clients : iOS peut dépendre d'un champ que le web n'utilise pas, et le web peut tenir compte d'un ordre ou d'une pagination que le mobile ignore.

Un exemple simple : l'app mobile dépend de price_cents comme entier. Le web n'affiche que le prix formaté, donc il ne remarquerait pas si le backend le changeait en chaîne. Un CDC venant du mobile attraperait ce changement avant la release.

Option 2 : schémas gérés par le fournisseur

Avec un schéma géré par le fournisseur, l'équipe backend publie un contrat unique (souvent un schéma ou une spec) et l'applique. Les consommateurs testent contre cette seule source de vérité.

C'est bien quand l'API est publique ou partagée entre de nombreux consommateurs que vous ne contrôlez pas, ou quand vous avez besoin d'une stricte cohérence entre équipes. C'est aussi plus simple pour démarrer : un contrat, un lieu pour les revues, un chemin d'approbation.

Voici un guide rapide pour choisir :

• Choisissez les CDCs quand les clients publient souvent et utilisent des parties différentes de l'API.
• Choisissez un schéma fournisseur quand vous avez besoin d'un contrat « officiel » stable pour tous.
• Utilisez un hybride quand vous le pouvez : un schéma fournisseur pour la base, plus des CDCs pour quelques endpoints à haut risque.

Si vous construisez avec une plateforme comme AppMaster, la même idée s'applique : traitez les apps web et natives comme des consommateurs séparés. Même s'ils partagent un backend, ils dépendent rarement exactement des mêmes champs et règles.

Que mettre dans un contrat d'API (pour qu'il détecte les vraies cassures)

Un contrat d'API n'aide que s'il reflète ce dont vos clients web et mobile dépendent vraiment. Une jolie spec que personne n'utilise ne détectera pas le changement qui casse la production.

Commencez par l'utilisation réelle, pas par des suppositions. Prenez les appels clients les plus fréquents (depuis le code de l'app, les logs de l'API gateway, ou une courte liste fournie par les équipes) et transformez-les en cas de contrat : le chemin exact, la méthode, les headers, les query params, et la forme typique du corps de la requête. Cela garde le contrat petit, pertinent et difficile à contester.

Incluez à la fois les réponses de succès et d'erreur. Les équipes testent souvent le happy path et oublient que les clients dépendent aussi des erreurs : le code de statut, la forme de l'erreur, et même des codes/messages d'erreur stables. Si une app mobile affiche un message spécifique « cet e-mail est déjà utilisé », un contrat devrait verrouiller cette réponse 409 afin qu'elle ne devienne pas soudainement un 400 avec un corps différent.

Faites particulièrement attention aux zones qui cassent le plus souvent :

• Champs optionnels vs requis : supprimer un champ est généralement plus sûr que rendre un champ optionnel requis.
• Nulls : certains clients traitent null différemment de « manquant ». Décidez ce que vous autorisez et restez cohérent.
• Enums : ajouter une nouvelle valeur peut casser les clients plus anciens qui supposent une liste fermée.
• Pagination : mettez-vous d'accord sur les paramètres et les champs de réponse (comme cursor ou nextPageToken) et gardez-les stables.
• Formats de dates et de nombres : rendez-les explicites (chaînes ISO, cents en entier, etc.).

Comment représenter le contrat

Choisissez un format que les équipes lisent et que les outils peuvent valider. Les options courantes sont JSON Schema, contrats basés sur des exemples, ou des modèles typés générés à partir d'une spec OpenAPI. En pratique, des exemples plus une validation de schéma fonctionnent bien : les exemples montrent des payloads réels, tandis que les règles de schéma attrapent les erreurs de type « champ renommé » ou « type changé ».

Une règle simple : si un changement oblige un client à être mis à jour, le test de contrat devrait échouer. Cette mentalité garde les contrats focalisés sur les vraies cassures, pas sur la perfection théorique.

Pas à pas : ajouter des tests de contrat dans votre pipeline CI

Le but des tests de contrat est simple : quand quelqu'un change l'API, votre CI doit vous dire si un client web ou mobile va casser avant que le changement ne soit déployé.

1) Commencez par capturer ce dont les clients dépendent réellement

Choisissez un seul endpoint et notez les attentes importantes en usage réel : champs requis, types, valeurs autorisées, codes de statut, et réponses d'erreur courantes. N'essayez pas de décrire toute l'API d'un coup. Pour les apps mobiles, incluez aussi les attentes des « anciennes versions de l'app », car les utilisateurs ne mettent pas toujours à jour immédiatement.

Une façon pratique de faire est de prendre quelques requêtes réelles que vos clients envoient aujourd'hui (depuis les logs ou des fixtures de test) et de les transformer en exemples reproductibles.

2) Placez les contrats là où les équipes vont les maintenir

Les contrats échouent quand ils vivent dans un dossier oublié. Gardez-les proches du code qui change :

• Si une même équipe possède les deux côtés, stockez les contrats dans le repo de l'API.
• Si des équipes différentes possèdent web, mobile et l'API, utilisez un repo partagé géré par les équipes, pas par une seule personne.
• Traitez les mises à jour de contrat comme du code : revues, versioning, et discussions.

3) Ajoutez des vérifications des deux côtés dans la CI

Vous voulez deux signaux :

• Vérification du provider à chaque build API : « l'API satisfait-elle toujours tous les contrats connus ? »
• Vérifications consumer à chaque build client : « ce client est-il toujours compatible avec le contrat publié le plus récent ? »

Cela attrape les problèmes dans les deux sens. Si l'API change un champ de réponse, le pipeline API échoue. Si un client commence à attendre un nouveau champ, le pipeline client échoue tant que l'API ne le fournit pas.

4) Décidez de la règle d'échec et appliquez-la

Soyez explicite sur ce qui bloque un merge ou une release. Une règle commune : tout changement cassant le contrat fait échouer la CI et bloque la fusion sur la branche principale. Si vous avez besoin d'exceptions, exigez une décision écrite (par exemple, une date de release coordonnée).

Exemple concret : un changement backend renomme totalPrice en total_amount. La vérification provider échoue immédiatement, donc l'équipe backend ajoute le nouveau champ tout en conservant l'ancien pendant une période de transition, et web et mobile continuent de livrer sans problème.

Versioning et compatibilité ascendante sans ralentir les équipes

Les équipes rapides cassent le plus souvent les APIs en changeant ce dont les clients existants dépendent. Un « changement cassant » est tout ce qui fait qu'une requête fonctionnait auparavant et ne fonctionne plus, ou rend la réponse significativement différente d'une façon que le client ne peut pas gérer.

Voici des changements cassants courants (même si l'endpoint existe toujours) :

• Suppression d'un champ de réponse que les clients lisent
• Changement de type d'un champ (par exemple "total": "12" en "total": 12)
• Rendre un champ optionnel obligatoire (ou ajouter un nouveau champ requis dans la requête)
• Changement des règles d'auth (un endpoint public nécessite maintenant un token)
• Changement des codes de statut ou de la forme des erreurs que les clients analysent (200 en 204, ou un nouveau format d'erreur)

La plupart des équipes peuvent éviter les versions majeures en choisissant des alternatives plus sûres. Si vous avez besoin de plus de données, ajoutez un nouveau champ au lieu d'en renommer un. Si vous avez besoin d'un meilleur endpoint, ajoutez une nouvelle route et gardez l'ancienne. Si vous devez durcir la validation, acceptez l'ancien et le nouveau format pendant un certain temps, puis appliquez progressivement la nouvelle règle. Les tests de contrat aident ici parce qu'ils vous obligent à prouver que les consommateurs existants reçoivent toujours ce à quoi ils s'attendent.

La dépréciation est la partie qui permet de garder la vitesse sans nuire aux utilisateurs. Les clients web peuvent se mettre à jour quotidiennement, mais les apps mobiles peuvent prendre des semaines à cause des files de validation et de l'adoption lente. Planifiez la dépréciation en fonction du comportement réel des clients, pas de l'espoir.

Une politique de dépréciation pratique ressemble à ceci :

• Annoncer le changement tôt (notes de release, canal interne, ticket)
• Garder l'ancien comportement jusqu'à ce que l'utilisation tombe en dessous d'un seuil convenu
• Retourner des avertissements dans les headers/logs quand le chemin déprécié est utilisé
• Fixer une date de suppression seulement après confirmation que la plupart des clients ont été mis à jour
• Supprimer l'ancien comportement seulement après que les tests de contrat montrent qu'aucun consommateur actif n'en a besoin

Utilisez le versioning explicite uniquement quand vous ne pouvez pas rendre un changement rétrocompatible (par exemple un changement fondamental de la forme d'une ressource ou du modèle de sécurité). Le versioning ajoute un coût à long terme : vous maintenez maintenant deux comportements, deux jeux de docs, et plus de cas limites. Gardez les versions rares et délibérées, et utilisez les contrats pour vous assurer que les deux versions restent conformes jusqu'à ce que l'ancienne soit sûre à supprimer.

Erreurs courantes en tests de contrat (et comment les éviter)

Les tests de contrat fonctionnent mieux quand ils vérifient des attentes réelles, pas une version édulcorée de votre système. La plupart des échecs viennent de quelques schémas prévisibles qui donnent un faux sentiment de sécurité pendant que des bugs glissent en production.

Erreur 1 : considérer les contrats comme des « mocks sophistiqués »

Le sur-mock est le piège classique : le test de contrat passe parce que le comportement du provider a été mocké pour correspondre au contrat, pas parce que le service réel peut réellement le faire. À la mise en production, la première requête réelle échoue.

Une règle plus sûre est simple : les contrats doivent être vérifiés contre le provider en cours d'exécution (ou un artefact de build qui se comporte de la même manière), avec une sérialisation réelle, une validation réelle, et des règles d'auth réelles.

Voici les erreurs qui apparaissent le plus souvent, et la correction qui tient généralement :

• Sur-mock du provider : vérifiez les contrats contre un build réel du provider, pas un service stubbe.
• Contrats trop stricts : utilisez un matching flexible pour les IDs, timestamps et tableaux ; évitez d'asserter chaque champ si les clients ne s'en servent pas.
• Ignorer les réponses d'erreur : testez au moins les principaux cas d'erreur (401, 403, 404, 409, 422, 500) et la forme du corps d'erreur que le client parse.
• Pas de propriété claire : attribuez qui met à jour le contrat quand les besoins changent ; faites-en partie de la « definition of done » des changements d'API.
• Oublier les réalités mobiles : testez en tenant compte de réseaux lents et d'anciennes versions d'app, pas seulement la dernière build sur un Wi‑Fi rapide.

Erreur 2 : contrats fragiles qui bloquent des changements innocents

Si un contrat échoue à chaque ajout d'un champ optionnel ou à chaque réordonnancement des clés JSON, les développeurs apprennent à ignorer la build rouge. Cela détruit l'objectif.

Visez « strict là où c'est important ». Soyez strict sur les champs requis, les types, les valeurs d'enum et les règles de validation. Soyez flexible sur les champs additionnels, l'ordre, et les valeurs qui varient naturellement.

Un petit exemple : votre backend passe status de "active" | "paused" à "active" | "paused" | "trial". Si une app mobile traite les valeurs inconnues comme un crash, c'est un changement cassant. Le contrat devrait le détecter en vérifiant comment le client gère les valeurs d'enum inconnues, ou en exigeant que le provider continue à renvoyer seulement des valeurs connues jusqu'à ce que tous les clients puissent gérer la nouvelle.

Les clients mobiles méritent une attention supplémentaire car ils restent plus longtemps en production. Avant d'appeler un changement d'API « sûr », demandez-vous :

• Les anciennes versions d'app peuvent-elles toujours parser la réponse ?
• Que se passe-t-il si la requête est retentée après un timeout ?
• Les données en cache vont-elles entrer en collision avec le nouveau format ?
• Avons-nous un fallback quand un champ est manquant ?

Si vos APIs sont générées ou mises à jour rapidement (y compris via des plateformes comme AppMaster), les contrats sont une garde-fou pratique : ils vous permettent d'avancer vite tout en prouvant que web et mobile continueront de fonctionner après chaque changement.

Checklist rapide avant la mise en production d'un changement d'API

Utilisez ceci juste avant de merger ou de release un changement d'API. Il est conçu pour attraper les petites modifications qui causent les plus gros incendies quand web et mobile publient souvent. Si vous faites déjà des tests de contrat, cette liste vous aide à vous concentrer sur les cassures que les contrats doivent bloquer.

Les 5 questions à se poser à chaque fois

• Avons-nous ajouté, supprimé ou renommé des champs de réponse que les clients lisent (y compris des champs imbriqués) ?
• Des codes de statut ont-ils changé (200 vs 201, 400 vs 422, 404 vs 410), ou le format du corps d'erreur a-t-il changé ?
• Des champs ont-ils basculé entre requis et optionnel (incluant « peut être null » vs « doit être présent ») ?
• Le tri, la pagination ou les filtres par défaut ont-ils changé (taille de page, ordre, jetons de curseur, valeurs par défaut) ?
• Les tests de contrat ont-ils été exécutés pour le provider et tous les consumers actifs (web, iOS, Android, et tous les outils internes) ?

Un exemple simple : votre API renvoyait totalCount, et un client l'utilise pour afficher « 24 résultats ». Vous le supprimez parce que « la liste a déjà des items ». Rien ne casse côté backend, mais l'UI commence à afficher vide ou « 0 résultats » pour certains utilisateurs. C'est une vraie cassure, même si l'endpoint renvoie toujours 200.

Si vous avez répondu « oui » à un des items

Faites ces vérifications rapides avant la mise en production :

• Confirmez si les anciens clients fonctionneront encore sans mise à jour. Si non, ajoutez un chemin rétrocompatible (conserver l'ancien champ, ou supporter les deux formats pendant un temps).
• Vérifiez le traitement des erreurs dans les clients. Beaucoup d'apps traitent une forme d'erreur inconnue comme « Quelque chose a échoué » et masquent des messages utiles.
• Lancez les tests de contrat consommateur pour chaque version client publiée que vous supportez encore, pas uniquement la branche la plus récente.

Si vous développez rapidement des outils internes (par exemple un panneau admin ou un dashboard de support), assurez-vous que ces consommateurs sont inclus aussi. Sur AppMaster, les équipes génèrent souvent des apps web et mobiles à partir des mêmes modèles backend, ce qui facilite l'oubli qu'un petit tweak de schéma peut quand même casser un client déjà publié si le contrat n'est pas vérifié en CI.

Exemple : attraper une cassure avant que web et mobile ne publient

Imaginez une configuration courante : l'équipe API déploie plusieurs fois par jour, l'app web publie quotidiennement, et les apps mobiles hebdomadairement (à cause des validations des stores et des déploiements progressifs). Tout le monde avance vite, donc le vrai risque n'est pas une mauvaise intention, mais de petits changements qui semblent anodins.

Un ticket support demande un nommage plus clair dans la réponse du profil utilisateur. L'équipe API renomme un champ dans GET /users/{id} de phone en mobileNumber.

Ce renommage paraît propre, mais c'est une cassure. Le client web peut afficher un numéro vide sur la page de profil. Pire, le client mobile peut planter s'il considère phone comme requis, ou échouer à valider lors de la sauvegarde du profil.

Avec des tests de contrat, cela est détecté avant d'atteindre les utilisateurs. Voici comment l'échec se produit typiquement, selon la façon dont vous exécutez les vérifications :

• La build provider échoue (côté API) : le job CI API vérifie le provider contre les contrats consommateurs sauvegardés du web et du mobile. Il voit que les consommateurs attendent toujours phone, mais le provider renvoie maintenant mobileNumber, donc la vérification échoue et le déploiement est bloqué.
• La build consumer échoue (côté client) : l'équipe web met à jour son contrat pour exiger mobileNumber avant que l'API ne le fournisse. Son test de contrat échoue parce que le provider ne fournit pas encore ce champ.

Dans les deux cas, l'échec est précoce, audible et précis : il pointe l'endpoint exact et le champ en désaccord, au lieu d'apparaître comme « la page profil est cassée » après la release.

La correction est généralement simple : rendre le changement additif, pas destructif. L'API renvoie les deux champs pendant un temps :

• Ajouter mobileNumber.
• Garder phone comme alias (même valeur).
• Marquer phone comme déprécié dans les notes du contrat.
• Mettre à jour web et mobile pour lire mobileNumber.
• Supprimer phone uniquement après avoir vérifié que toutes les versions clientes supportées ont migré.

Une timeline réaliste sous pression de release peut ressembler à ceci :

• Lun 10:00 : l'équipe API ajoute mobileNumber et conserve phone. Les tests provider passent.
• Lun 16:00 : le web passe à mobileNumber et publie.
• Jeu : le mobile passe à mobileNumber et soumet une release.
• Mar : la release mobile atteint la plupart des utilisateurs.
• Sprint suivant : l'API supprime phone, et les tests de contrat confirment qu'aucun consumer supporté n'en a encore besoin.

C'est la valeur clé : les tests de contrat transforment la « roulette du changement cassant » en une transition contrôlée et planifiée.

Étapes suivantes pour les équipes qui avancent vite (y compris une option sans-code)

Si vous voulez que les tests de contrat empêchent réellement les cassures (et pas seulement ajouter des vérifications), gardez le déploiement restreint et clarifiez la propriété. Le but est simple : attraper les changements cassants avant qu'ils n'affectent les releases web et mobile.

Commencez par un déploiement léger. Choisissez les 3 endpoints principaux qui créent le plus de douleur lorsqu'ils changent, généralement auth, profil utilisateur, et un endpoint central de type « liste » ou « recherche ». Mettez-les sous contrat en premier, puis étendez une fois que l'équipe fait confiance au workflow.

Un déroulé pratique et gérable :

• Semaine 1 : tests de contrat pour les 3 endpoints prioritaires, exécutés à chaque pull request
• Semaine 2 : ajouter les 5 endpoints suivants avec le plus d'usage mobile
• Semaine 3 : couvrir les réponses d'erreur et cas limites (états vides, erreurs de validation)
• Semaine 4 : faire du « contrat vert » une condition de release pour les changements backend

Ensuite, décidez qui fait quoi. Les équipes vont plus vite quand il est évident qui possède une défaillance et qui approuve un changement.

Gardez les rôles simples :

• Propriétaire du contrat : généralement l'équipe backend, responsable de la mise à jour des contrats quand le comportement change
• Relecteurs consommateurs : leads web et mobile qui confirment que les changements sont sûrs pour leurs clients
• Build sheriff : rotation quotidienne ou hebdomadaire, triage des échecs de tests de contrat en CI
• Responsable release : prend la décision de bloquer une release si un contrat est cassé

Suivez une métrique de succès que tout le monde comprend. Pour beaucoup d'équipes, le meilleur signal est moins de hotfixes après les releases et moins de « régressions client » comme des plantages d'app, écrans vides, ou checkout cassé liés à des changements d'API.

Si vous voulez un retour encore plus rapide, les plateformes no-code peuvent réduire la dérive en régénérant du code propre après les changements. Quand la logique ou les modèles de données bougent, la régénération aide à éviter l'accumulation lente de patches qui changent accidentellement le comportement.

Si vous construisez APIs et clients avec AppMaster, une prochaine étape pratique est d'essayer maintenant : créez une application, modélisez vos données dans le Data Designer (PostgreSQL), mettez à jour les workflows dans le Business Process Editor, puis régénérez et déployez sur votre cloud (ou exportez le code source). Associez cela à des vérifications de contrat dans votre CI afin que chaque build régénéré prouve toujours qu'il correspond à ce que web et mobile attendent.