Versionner une API pour apps mobiles : faire évoluer les endpoints sans casser les clients

Pourquoi les changements d’API cassent les utilisateurs mobiles

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 :

• L’authentification ou l’inscription échoue après une mise à jour backend
• Les listes semblent vides parce qu’un champ a été renommé ou déplacé
• L’app plante en lisant une valeur manquante
• Les paiements échouent parce que la validation est plus stricte
• Des fonctionnalités disparaissent silencieusement parce que la forme de la réponse a changé

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.

Ce que signifie « compatible » pour un contrat d’API

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 :

• Breaking changes : suppression ou renommage d’un champ, changement de type (nombre → chaîne), rendre un champ optionnel obligatoire, changer le format d’erreur, durcir la validation de façon que les anciennes apps ne satisfassent plus.
• Changements généralement sûrs : ajout d’un nouveau champ optionnel, ajout d’un nouvel endpoint, accepter d’ancien et nouveau formats de requête, ajouter des valeurs d’énumération (seulement si l’app traite les valeurs inconnues comme « autre »).

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.

Approches courantes de versioning et compromis

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.

Versioning dans l’URL

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.

Versioning via les en-têtes

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.

Versioning via paramètre de 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 :

• Versioning URL : le plus facile à inspecter, mais peut créer des APIs parallèles qui vivent longtemps
• Versioning header : URLs propres, mais plus difficile à dépanner
• Versioning query : rapide à démarrer, facile à mal utiliser

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 ».

Règles pratiques pour les changements rétrocompatibles

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 :

• Ajoutez des champs, mais ne changez pas le type ou le sens des champs existants.
• Traitez les entrées manquantes comme normales et utilisez des valeurs par défaut sensées.
• Ignorez les champs de requête inconnus pour que anciens et nouveaux clients coexistent.
• Gardez le format des erreurs stable. Si vous devez le changer, versionnez le payload d’erreur.
• Si le comportement doit changer, introduisez un nouvel endpoint ou une nouvelle version plutôt qu’un « tweak » silencieux.

É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.

Définir une politique simple de versioning et de dépréciation

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 :

1. Retourner un avertissement doux (par exemple un champ qui déclenche une invite de mise à jour dans l’app).
2. N’appliquer une restriction qu’après un délai communiqué.

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 :

• Un propriétaire approuve les breaking changes.
• Une note de changement courte explique ce qui a changé, qui est affecté et le chemin de migration.
• Un plan de test inclut au moins une ancienne version d’app.
• Une date de retrait est fixée au début de la dépréciation.

Plan de déploiement étape par étape qui garde les anciennes apps fonctionnelles

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 :

• volume de requêtes v1 vs v2 par version d’app
• taux d’erreur et latence pour v2
• échecs d’analyse de réponse
• plantages liés aux écrans réseau

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.

Conseils d’implémentation côté serveur

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.

Placez le routage de version derrière une seule porte

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 :

• Parsez la version une fois (et loggez-la).
• Mappez la version à un handler (v1, v2, ...) dans un registre unique.
• Gardez les utilitaires partagés agnostiques de version (parsing de date, vérifications d’auth), pas la logique de forme de réponse.

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.

Gardez les changements de données compatibles pendant le rollout

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.

Considérations côté mobile qui affectent le versioning

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.

• Ignorez les champs JSON inconnus.
• Traitez les champs manquants comme normaux et utilisez des valeurs par défaut.
• Gérez les nulls sans planter (les champs peuvent devenir nullables pendant des migrations).
• Ne dépendez pas de l’ordre des tableaux sauf si le contrat le garantit.
• Gardez le traitement des erreurs convivial (un état de réessai vaut mieux qu’un écran vide).

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.

Surveillance et rollouts progressifs sans surprises

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 :

• taux d’erreur au-dessus d’un seuil fixe pendant 15–30 minutes
• baisse du taux de connexion (ou augmentation des échecs de refresh token)
• hausse des échecs de paiement (ou allongement des timeouts du checkout)
• pic de tickets support lié à une version précise
• augmentation de la latence sur un endpoint critique

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.

Exemple : faire évoluer un endpoint lors d’une release réelle

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.

Ce qui reste en v1 vs ce qui change en v2

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.

• v1 conserve : amount, currency, card_token, et une réponse unique comme status=paid|failed.
• v2 ajoute : 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).
• v2 renomme : 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.

Adoption, retrait et rollback

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 :

• Orientez plus de trafic vers le comportement v1.
• Désactivez l’étape de paiement nouvelle via un flag serveur.
• Continuez d’accepter les deux jeux de champs et loggez ce que vous avez auto-converti.

Erreurs fréquentes qui provoquent des ruptures silencieuses

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 :

• Changer ou supprimer des champs (ou leur type) sans plan de version clair.
• Rendre un nouveau champ de requête immédiatement obligatoire, si bien que les anciennes apps sont rejetées.
• Publier une migration de base de données qui suppose que seule la nouvelle app existe.
• Retirer v1 en se basant sur les installations plutôt que l’usage actif.
• Oublier les jobs background et webhooks qui envoient encore de vieux payloads.

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.

Checklist rapide et prochaines étapes

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.

Vérifications rapides avant la release

• Favorisez les changements additifs. Ne supprimez pas ou ne renommez pas les champs que les anciennes apps lisent.
• Fournissez des valeurs par défaut sûres pour que les champs nouveaux manquants se comportent comme avant.
• Gardez les réponses d’erreur stables (status + forme + signification).
• Traitez les enums avec soin et ne changez pas la signification d’une valeur existante.
• Rejouez quelques requêtes réelles d’anciennes versions d’app et confirmez que les réponses se parsèment toujours.

Vérifications rapides pendant le rollout et avant le retrait

• Suivez l’adoption par version d’app. Vous voulez une courbe claire de v1 vers v2, pas une ligne plate.
• Surveillez les taux d’erreur par version. Un pic indique souvent un problème de parsing ou validation pour les anciens clients.
• Corrigez d’abord le endpoint le plus défaillant, puis élargissez le rollout.
• Retirez seulement quand l’usage actif est vraiment faible, et communiquez la date.
• Supprimez le code de fallback en dernier, après la fenêtre de dépréciation.

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.