Versioning d’API pour apps mobiles expliqué avec un plan de déploiement simple, des changements rétrocompatibles et des étapes de dépréciation pour que les anciennes versions restent fonctionnelles.
Les applications mobiles ne se mettent pas toutes à jour en même temps. Même si vous publiez un correctif aujourd’hui, beaucoup de personnes garderont une ancienne version pendant des jours ou des semaines. Certains désactivent les mises à jour automatiques. D’autres manquent d’espace. Certains n’ouvrent tout simplement pas l’app souvent. Le délai des validations sur les stores et les releases progressives ajoutent encore du retard.
Cet écart compte parce que votre backend évolue généralement plus vite que vos clients mobiles. Si le serveur modifie un endpoint et que l’ancienne app continue de l’appeler, l’app peut se casser même si rien n’a changé sur le téléphone de l’utilisateur.
Les régressions n’apparaissent que rarement comme un message d’erreur clair. Elles ressemblent plutôt à des problèmes produits quotidiens :
Le but du versioning est simple : continuer à améliorer le serveur sans forcer tout le monde à mettre à jour immédiatement. Traitez votre API comme un contrat de long terme. Les nouvelles versions de l’app doivent fonctionner avec le comportement serveur neuf, et les versions plus anciennes doivent rester opérationnelles assez longtemps pour respecter les cycles de mise à jour réels.
Pour la plupart des applications grand public, attendez-vous à supporter plusieurs versions d’app en parallèle. Les apps internes peuvent parfois aller plus vite, mais ce n’est rarement instantané. Planifier le chevauchement évite que chaque release backend ne devienne un pic de support.
Un contrat d’API est la promesse entre votre app mobile et votre serveur : quelle URL appeler, quelles entrées sont acceptées, à quoi ressemble la réponse et que signifie chaque champ. Quand l’app dépend de cette promesse et que le serveur la modifie, les utilisateurs le ressentent sous forme de plantages, données manquantes ou fonctionnalités qui cessent de fonctionner.
Un changement est compatible quand les anciennes versions de l’app peuvent continuer à utiliser l’API sans changer de code. Concrètement, cela signifie que le serveur comprend toujours ce que les anciennes apps envoient et renvoie des réponses que ces apps peuvent parser.
Une façon rapide de séparer les changements sûrs des changements risqués :
La compatibilité nécessite aussi un plan de fin de vie. Retirer un comportement ancien est acceptable, mais cela doit être programmé (par exemple « conserver v1 pendant 90 jours après le lancement de v2 ») afin d’évoluer sans surprendre les utilisateurs.
Le versioning vise à offrir aux builds plus anciennes un contrat stable pendant que vous avancez. Il existe plusieurs approches courantes, chacune déplaçant la complexité ailleurs.
Mettre la version dans le chemin (par exemple /v1/ et /v2/) est le plus simple à voir et à déboguer. Cela fonctionne bien avec le cache, le logging et le routage parce que la version fait partie de l’URL. Le revers est que les équipes peuvent finir par maintenir des handlers parallèles plus longtemps que prévu, même quand la différence est minime.
Avec le versioning par en-tête, le client envoie une version dans un header (par exemple un Accept ou un header personnalisé). Les URLs restent propres et vous pouvez faire évoluer l’API sans changer chaque chemin. L’inconvénient est la visibilité : les proxys, les logs et les humains ratent souvent la version à moins d’être vigilants, et les clients mobiles doivent définir l’en-tête de façon fiable sur chaque requête.
Le versioning par paramètre (comme ?v=2) semble simple, mais devient vite bordélique. Les paramètres se retrouvent dans des bookmarks, outils d’analyse et scripts, et vous pouvez vous retrouver avec plusieurs « versions » flottantes sans propriété claire.
Si vous voulez une comparaison simple :
Les feature flags sont un autre outil. Ils permettent de changer le comportement derrière le même contrat (par exemple un nouvel algorithme de classement) sans créer une nouvelle version d’API. Ils ne remplacent pas le versioning quand la forme des requêtes ou des réponses doit changer.
Choisissez une approche et tenez-vous-y. La cohérence compte plus que le choix « parfait ».
La mentalité la plus sûre : les clients plus anciens doivent continuer à fonctionner même s’ils n’apprennent jamais votre nouvelle fonctionnalité. Cela signifie généralement ajouter des choses, pas changer ce qui existe déjà.
Privilégiez les changements additifs : nouveaux champs, nouveaux endpoints, nouveaux paramètres optionnels. Quand vous ajoutez quelque chose, rendez-le vraiment optionnel côté serveur. Si une ancienne app ne l’envoie pas, le serveur doit se comporter exactement comme avant.
Quelques habitudes évitent la plupart des régressions :
Évitez de changer la signification d’un champ existant sans incrément de version. Par exemple, si status=1 signifiait « payé » et que vous le réutilisez pour « autorisé », les anciennes apps prendront de mauvaises décisions et vous pourriez ne pas le remarquer avant les plaintes.
Les renommages et suppressions exigent un plan. Le schéma le plus sûr est de garder l’ancien champ et d’ajouter le nouveau en parallèle un certain temps. Renseignez les deux dans les réponses, acceptez les deux dans les requêtes et loggez qui utilise encore l’ancien champ. Supprimez l’ancien champ seulement après la fenêtre de dépréciation.
Une petite habitude puissante : quand vous introduisez une nouvelle règle métier requise, ne demandez pas au client de la prendre en charge dès le premier jour. Appliquez la règle côté serveur avec une valeur par défaut d’abord, puis exigez que le client envoie la nouvelle valeur quand la majorité des utilisateurs sera mise à jour.
Le versioning marche mieux quand les règles sont ennuyeuses et écrites. Gardez la politique assez courte pour que produit, mobile et backend la suivent vraiment.
Commencez par des fenêtres de support. Décidez combien de temps vous garderez d’anciennes versions d’API actives après la sortie d’une nouvelle (par exemple 6–12 mois), plus des exceptions (sécurité, obligations légales).
Ensuite, définissez comment vous prévenez les clients avant de les casser. Choisissez un signal de dépréciation et utilisez-le partout. Options courantes : un en-tête de réponse Deprecation: true avec une date de retrait, ou un champ JSON comme "deprecation": {"will_stop_working_on": "2026-04-01"} sur certaines réponses. L’important est la cohérence : les clients peuvent le détecter, les tableaux de bord le rapporter, et le support l’expliquer.
Définissez une version minimale d’app supportée et soyez explicite sur l’application de cette règle. Évitez les blocages surprises. Une approche pratique :
Si vous bloquez les requêtes, retournez un payload d’erreur clair avec un message humain et un code machine lisible.
Enfin, décidez qui peut approuver les breaking changes et quelle documentation est requise. Gardez-le simple :
Les utilisateurs mobiles ne mettent pas tous à jour le même jour. L’approche la plus sûre est de publier une nouvelle API tout en laissant l’ancienne intacte, puis transférer le trafic progressivement.
D’abord, définissez ce que fait v2 et verrouillez le comportement de v1. Traitez v1 comme une promesse : mêmes champs, mêmes sens, mêmes codes d’erreur. Si v2 nécessite une forme de réponse différente, ne modifiez pas v1 pour qu’elle corresponde.
Ensuite, exécutez v2 en parallèle. Cela peut signifier des routes séparées (comme /v1/... et /v2/...) ou des handlers séparés derrière la même gateway. Conservez la logique partagée à un seul endroit, mais gardez le contrat séparé pour qu’un refactor v2 ne change pas accidentellement v1.
Puis mettez à jour l’app mobile pour préférer v2. Implémentez un fallback simple : si v2 renvoie "not supported" (ou une autre erreur connue), retenter en v1. Cela aide pendant les releases progressives et quand les réseaux réels deviennent compliqués.
Après la sortie de l’app, surveillez l’adoption et les erreurs. Vérifications utiles :
Quand v2 est stable, ajoutez des avertissements de dépréciation clairs pour v1 et communiquez un calendrier. Retirez v1 seulement quand l’usage passe sous un seuil acceptable (par exemple <1–2% pendant plusieurs semaines).
Exemple : vous changez GET /orders pour supporter le filtrage et de nouveaux statuts. v2 ajoute status_details tandis que v1 reste identique. La nouvelle app appelle v2, mais si elle tombe sur un cas limite elle retombe sur v1 et affiche toujours la liste des commandes.
La plupart des régressions pendant les rollouts surviennent parce que la gestion des versions est dispersée dans les contrôleurs, helpers et le code de base de données. Gardez la décision « quelle version pour cette requête ? » en un seul endroit, et le reste du code doit rester prévisible.
Choisissez un signal (segment d’URL, header, ou numéro de build de l’app) et normalisez-le tôt. Routez vers le bon handler dans un module ou middleware unique pour que chaque requête suive le même chemin.
Un pattern pratique :
Faites attention au partage de code entre versions. Corriger un bug v2 dans du code « partagé » peut changer accidentellement le comportement v1. Si la logique affecte les champs de sortie ou les règles de validation, gardez-la versionnée ou couvrez-la par des tests spécifiques à la version.
Les migrations de base doivent fonctionner pour les deux versions en même temps. Ajoutez d’abord des colonnes, backfillez si nécessaire, puis supprimez ou resserrez les contraintes plus tard. Évitez de renommer ou de changer la sémantique en plein rollout. Si vous devez supporter deux formats, écrivez les deux formats pendant une courte période jusqu’à ce que la majorité des clients migre.
Rendez les erreurs prévisibles. Les anciennes apps interprètent souvent les erreurs inconnues comme « quelque chose s’est mal passé ». Utilisez des status codes cohérents, des identifiants d’erreur stables et des messages courts qui aident le client à décider (réessayer, se réauthentifier, inviter à mettre à jour).
Enfin, protégez-vous contre les champs manquants que les anciennes apps n’envoient pas. Utilisez des valeurs par défaut sûres et validez avec des détails d’erreur clairs et stables.
Puisque les utilisateurs peuvent rester sur une ancienne build pendant des semaines, le versioning doit supposer que plusieurs versions clientes toucheront vos serveurs en même temps.
Un gros avantage est la tolérance côté client. Si l’app plante ou n’arrive pas à parser quand le serveur ajoute un champ, vous verrez des bugs « aléatoires » de rollout.
Le comportement réseau compte aussi. Pendant un rollout vous pouvez avoir brièvement des versions de serveurs mixtes derrière des load balancers ou caches, et les réseaux mobiles amplifient les petits soucis.
Choisissez des règles claires de timeout et retry : timeouts courts pour les lectures, un peu plus longs pour les uploads, et des retries limités avec backoff. Rendre l’idempotence standard pour les appels de création ou de paiement évite les doubles envois lors d’un retry.
Les changements d’auth sont la manière la plus rapide d’exclure les anciennes apps. Si vous changez le format du token, les scopes requis ou les règles de session, gardez une fenêtre de chevauchement où anciens et nouveaux tokens sont acceptés. Si vous devez faire une rotation de clés ou de claims, planifiez une migration progressive, pas une coupure le même jour.
Envoyez les métadonnées de l’app avec chaque requête (par exemple version d’app et plateforme). Cela facilite le retour d’avertissements ciblés sans forker l’API entière.
Un déploiement progressif ne fonctionne que si vous voyez ce que font les différentes versions d’app. Le but est simple : savoir qui est encore sur d’anciens endpoints et détecter les problèmes avant qu’ils n’affectent tout le monde.
Commencez par suivre l’usage par version d’API chaque jour. Ne comptez pas seulement les requêtes totales. Suivez les appareils actifs et segmentez les endpoints clés comme login, profil et paiements. Cela vous indique si une ancienne version est toujours « vivante » même si le trafic total semble faible.
Ensuite surveillez les erreurs par version et par type. Une hausse des 4xx indique souvent un décalage de contrat (champ requis changé, valeurs d’énumération déplacées, règles d’auth plus strictes). Une hausse des 5xx pointe souvent vers des régressions serveur (mauvais déploiement, requêtes lentes, défaillance d’un dépendance). Voir les deux par version aide à choisir la bonne action rapidement.
Utilisez des rollouts par étapes dans les stores pour limiter la zone d’impact. Augmentez l’exposition par paliers et observez les mêmes tableaux après chaque étape (par ex. 5%, 25%, 50%). Si la nouvelle version montre des problèmes, arrêtez le rollout avant une panne générale.
Ayez des déclencheurs de rollback écrits à l’avance, pas décidés pendant l’incident. Déclencheurs fréquents :
Gardez un petit playbook d’incident pour les pannes liées aux versions : qui pager, comment désactiver un flag risqué, quelle release serveur rollbacker, et comment prolonger la fenêtre de dépréciation si des clients anciens sont toujours actifs.
Le checkout est un changement classique en production. Vous commencez avec un flux simple, puis vous ajoutez une étape de paiement (authentification plus forte) et renommez des champs pour coller au vocabulaire métier.
Supposons que votre app mobile appelle POST /checkout.
En v1, conservez la requête et le comportement existants pour que les anciennes builds puissent finir les paiements sans surprise. En v2, introduisez le nouveau flux et des noms plus propres.
amount, currency, card_token, et une réponse unique comme status=paid|failed.payment_method_id (remplaçant card_token) et un champ next_action pour que l’app gère une étape supplémentaire (vérifier, réessayer, rediriger).amount en total_amount et currency en billing_currency.Les anciennes apps continuent de fonctionner parce que le serveur applique des valeurs par défaut sûres. Si une requête v1 ne connaît pas next_action, le serveur complète le paiement quand c’est possible et renvoie le résultat au format v1. Si la nouvelle étape est requise, v1 reçoit un code d’erreur clair et stable comme requires_update au lieu d’un échec générique confus.
Suivez l’adoption par version : part des appels checkout sur v2, taux d’erreur, et combien d’utilisateurs tournent encore sur des builds qui ne prennent en charge que v1. Quand l’usage de v2 est constamment élevé (par ex. ≥95% plusieurs semaines) et que l’usage de v1 est faible, fixez une date de retrait de v1 et communiquez-la (notes de release, messages in-app).
Si quelque chose se passe mal après le lancement, le rollback doit être banal :
La plupart des pannes mobiles ne font pas de bruit. La requête réussit, l’app tourne, mais les utilisateurs voient des données manquantes, des totaux erronés ou des boutons inactifs. Ces problèmes sont difficiles à repérer car ils frappent souvent des versions d’app anciennes pendant un rollout progressif.
Causes courantes :
Un exemple concret : votre champ de réponse total était une chaîne ("12.50") et vous le transformez en nombre (12.5). Les nouvelles apps vont bien. Les anciennes peuvent le traiter comme zéro, le cacher, ou planter seulement sur certains écrans. Sans surveillance des erreurs par version d’app, cela peut passer inaperçu.
Le versioning porte moins sur le nom des endpoints que sur la répétition des mêmes contrôles de sécurité à chaque release.
Rédigez votre politique de versioning et de dépréciation sur une seule page, puis transformez la checklist en une gate de release que l’équipe suit à chaque fois.
Si vous construisez des outils internes ou des apps client avec une plateforme no-code, cela reste utile de traiter l’API comme un contrat avec une fenêtre de dépréciation claire. Pour les équipes utilisant AppMaster (appmaster.io), garder v1 et v2 côte à côte est souvent plus simple car vous pouvez régénérer backend et clients au fur et à mesure tout en maintenant les anciens contrats pendant le rollout.
Pourquoi les changements côté backend cassent-ils les applications mobiles alors que les utilisateurs n’ont rien mis à jour ?Les utilisateurs mobiles ne mettent pas tous l’app à jour en même temps, donc des versions plus anciennes continuent d’appeler votre backend après un déploiement. Si vous changez un endpoint, la validation ou la forme de la réponse, ces anciennes versions ne peuvent pas s’adapter et elles échouent, avec des symptômes comme des écrans vides, des plantages ou des paiements qui n’aboutissent pas.
Que signifie réellement « rétrocompatible » pour une API mobile ?« Compatible » signifie qu’une application plus ancienne peut continuer à faire les mêmes requêtes et recevoir des réponses qu’elle sait analyser et utiliser correctement, sans modification du code. Le modèle mental simple : l’API est un contrat ; vous pouvez ajouter des capacités, mais ne changez pas la signification des champs et comportements existants pour les clients actuels.
Quels sont les changements les plus courants qui provoquent des ruptures dans les API mobiles ?Un changement est bloquant quand il modifie quelque chose dont une app existante dépend : suppression ou renommage de champs, changement de type, validation plus stricte qui rejette d’anciennes requêtes, ou modification du format d’erreur. Si une ancienne app ne peut plus parser la réponse ou satisfaire les règles de la requête, c’est une rupture, même si le serveur semble « fonctionner ».
Dois-je utiliser le versioning par URL ou par header pour une API mobile ?Le versioning dans l’URL est souvent le choix par défaut parce que la version est visible dans les logs, les outils de debug et le routage ; il est difficile d’oublier de l’envoyer. Le versioning par header marche aussi, mais il est plus facile à rater lors du dépannage et oblige chaque requête cliente à définir correctement l’en-tête.
Combien de temps devons-nous garder les anciennes versions d’une API actives ?Choisissez une fenêtre de support claire qui correspond au comportement réel de mise à jour mobile, et tenez-vous-y : beaucoup d’équipes choisissent des mois plutôt que des jours. L’essentiel est d’avoir une date de retrait publiée et de mesurer l’usage actif pour ne pas deviner quand il est sûr d’arrêter une ancienne version.
Quelle est une façon pratique d’alerter les clients qu’une version d’API va être retirée ?Utilisez un signal de dépréciation cohérent et unique pour que les clients et les tableaux de bord puissent le détecter de façon fiable, par exemple un en-tête de réponse stable ou un petit champ JSON contenant la date de retrait. Restez simple et prévisible pour que le support et les équipes produit puissent l’expliquer facilement.
Comment faire évoluer les réponses sans casser les anciennes versions d’app ?Favorisez les changements additifs : ajoutez des champs optionnels ou de nouveaux endpoints, et conservez les anciens champs avec la même signification. Pour un renommage, gardez les deux champs en parallèle pendant un temps et remplissez les deux pour que les anciennes apps ne perdent pas de données pendant que les nouvelles passent au nouveau champ.
Comment gérer les changements de base de données quand v1 et v2 sont actives ?Concevez les migrations pour que les deux versions d’API fonctionnent simultanément : ajoutez d’abord des colonnes, backfillez si nécessaire, puis resserrez les contraintes ou supprimez d’anciens champs plus tard. Évitez de renommer ou de changer la sémantique au milieu d’un déploiement, sinon une version écrira des données que l’autre ne pourra pas lire.
Que doivent faire les applications mobiles pour être plus résilientes aux changements d’API ?Rendez l’app cliente tolérante : ignorez les champs JSON inconnus, traitez les champs manquants comme normaux avec des valeurs par défaut sûres, et gérez les nulls sans planter. Cela réduit les bugs « aléatoires » pendant les déploiements où le serveur ajoute des champs ou les réponses varient temporairement.
Que devons-nous surveiller pendant un déploiement progressif et quand est-il sûr de retirer v1 ?Surveillez l’usage et les erreurs par version d’API et par version d’app, en particulier pour les endpoints critiques comme l’authentification et les paiements. Élargissez les déploiements progressifs uniquement lorsque les données sont stables. Un plan sûr verrouille le comportement v1, exécute v2 en parallèle et migre les clients progressivement avec des stratégies de fallback claires jusqu’à ce que l’adoption permette de retirer v1 en toute confiance.
10 mars 2026
7 min
08 mars 20269 min
07 mars 20267 minExpérimentez avec AppMaster avec un plan gratuit.
Lorsque vous serez prêt, vous pourrez choisir l'abonnement approprié.
