Faire évoluer des API pour applis mobiles et partenaires : versions, compatibilité et retrait

EN BREF : Un site web se met à jour quand on veut ; une appli installée sur les téléphones des utilisateurs et le système d’un partenaire, non. Une fois une API publiée, partez du principe que ses appelants peuvent ne pas se mettre à jour avant longtemps. Nos règles : les changements compatibles vont dans la version existante, les changements incompatibles dans une nouvelle ; l’ancienne version est dépréciée et son usage mesuré par appelant ; elle n’est retirée que lorsque l’usage le permet ; et le contrat vit dans un fichier que la CI vérifie.

Schéma du cycle de vie d'une version d'API. /v1 est active et ne reçoit que des changements additifs ; un changement incompatible ouvre /v2 ; /v1 est ensuite dépréciée avec les en-têtes Deprecation et Sunset, puis retirée avec une erreur explicite. En dessous : le suivi d'usage de /v1 par version d'appli et clé partenaire, avec retrait seulement quand l'usage le permet ; et un fichier de contrat (OpenAPI) comparé en CI à la dernière version, où tout changement incompatible hors nouvelle version échoue.
Figure 1. Une version majeure, d'active à dépréciée puis retirée. Le retrait suit l'usage, pas le calendrier.

1.0 Ce qui compte comme compatible

ChangementCompatible ?
Nouveau champ de requête optionnel, nouveau champ de réponseOui, si les clients ignorent les champs inconnus
Nouvel endpointOui
Supprimer ou renommer un champ, changer son typeNon
Rendre obligatoire un champ optionnelNon
Ajouter une valeur d’énumérationDépend de la façon dont les clients traitent les valeurs inconnues ; par prudence, le traiter comme incompatible
Changer des codes d’erreur ou le tri par défautSouvent considéré comme compatible, mais casse les clients qui en dépendent

C’est dans les deux dernières lignes que surviennent les incidents. Dès la première version, nos consignes côté client exigent un affichage de repli pour une valeur d’énumération inconnue au lieu d’un plantage.

2.0 Où placer la version

Un segment de chemin comme /v1/ est le plus visible et s’accorde bien avec les journaux, le routage de la passerelle et les caches ; c’est notre choix par défaut. Un en-tête paraît plus propre mais passe facilement inaperçu pendant le débogage. Où qu’elle soit, la version ne change que pour un changement incompatible ; elle ne suit pas le numéro de version du produit.

Au sein d’une version majeure, le serveur a parfois besoin de petites différences de comportement selon la version du client. Faites envoyer la version de l’appli dans un en-tête et décidez côté serveur, plutôt que de créer une succession de versions mineures de l’API.

3.0 Le contrat est un fichier

Décrivez l’API dans un fichier comme OpenAPI et conservez-le dans le dépôt. La CI fait deux choses : elle compare la modification au contrat de la dernière version publiée et fait échouer le build sur tout changement incompatible qui ne se trouve pas dans une nouvelle version, et elle exécute des tests de contrat pour vérifier que l’implémentation correspond à la description.

Pour les API partenaires, le fichier de contrat est la source du guide développeur, pas un document tenu à part. Deux documents rédigés séparément finissent toujours par se contredire.

4.0 Dépréciation et retrait

  1. À la sortie d’une nouvelle version, les réponses de l’ancienne portent les en-têtes Deprecation et Sunset (RFC 9745, RFC 8594), et la documentation indique la date de retrait.
  2. Mesurer l’usage de l’ancienne version par appelant : quelles versions d’appli et quelles clés partenaires appellent encore.
  3. Pour le mobile, ajouter une version minimale prise en charge : le serveur la publie et les applis plus anciennes invitent l’utilisateur à mettre à jour.
  4. Ne retirer qu’une fois l’usage descendu à un niveau acceptable. Après le retrait, renvoyer un code d’erreur explicite avec des instructions de mise à jour plutôt qu’un 404 sec.

La date de retrait doit tenir compte de la revue des magasins d’applications et des habitudes de mise à jour des utilisateurs, et les partenaires ont besoin de temps pour développer, tester et livrer de leur côté.

5.0 Idempotence et relances

Sur les réseaux mobiles, les relances sont la norme. Les endpoints de création acceptent une clé d’idempotence : le client en génère une par opération et, pendant un certain temps, le serveur renvoie le même résultat pour la même clé. Les problèmes du type commande envoyée deux fois sont arrêtés dès le protocole.

Pour concevoir des API destinées à une appli ou à des partenaires, ou remettre d’aplomb une API devenue incontrôlable, voir Web, cloud et gestion des équipements, ou parlez-nous de votre projet.

Références

Questions fréquentes

Les endpoints utilisés uniquement par notre propre front web exigent-ils autant de rigueur ?

Un front web livré et annulé en même temps que le backend peut être traité plus souplement, tant que le contrôle de contrat continue de tourner. Dès qu'un client ne peut pas sortir au même rythme que le serveur, application mobile, mini-programme ou système externe, les règles de cette note s'appliquent.

GraphQL rend-il le versionnage inutile ?

L'usage en GraphQL est d'éviter les versions et d'évoluer en ajoutant des champs et en marquant les anciens comme dépréciés, ce qui revient à la même discipline de compatibilité sous une autre forme. Avant de supprimer un champ, il faut toujours savoir qui l'interroge encore.

Combien de temps garder une ancienne version ?

Il n'y a pas de réponse générale ; cela dépend de la vitesse de mise à jour des utilisateurs et des cycles de livraison des partenaires. Nous décidons d'après l'usage réel et annonçons la date de retrait dès la sortie de la nouvelle version, pour que les appelants puissent s'organiser.

Nous avons refactorisé en interne. L'API publique doit-elle changer aussi ?

L'API décrit un engagement envers l'extérieur, pas la structure interne. Faire la correspondance côté serveur et garder le contrat externe stable est en général la manière la moins coûteuse de traverser une refactorisation interne.