9 changements d'API qui font planter votre application

9 changements d'API qui font planter votre application

« Nous n'avons rien cassé. Nous avons simplement nettoyé la réponse. »

Ces mots mènent souvent à des plantages. Une application mobile échoue. Une intégration partenaire renvoie des données erronées. Vous avez modifié la structure des données dont d'autres dépendent.

Les changements dangereux ressemblent souvent à un simple nettoyage. Ils passent les revues de code et les tests. La rupture survient dans du code que vous ne pouvez pas voir.

Voici neuf changements qui semblent sûrs, mais qui ne le sont pas.

• Renommer des champs Passer de userId à user_id pour plus de cohérence casse les clients. Un renommage est une suppression suivie d'un ajout. La partie suppression impacte les utilisateurs. Approche sûre : Ajoutez le nouveau champ. Conservez l'ancien. Dépréciez-le. Supprimez-le bien plus tard.

• Rendre un champ optionnel Un champ était systématiquement présent. Désormais, il est parfois null. Le code client plante lorsqu'il tente de le traiter. Approche sûre : Considérez la présence systématique comme une promesse. Si un champ devient optionnel, utilisez une nouvelle version.

• Supprimer des champs inutilisés Vous ne pouvez pas voir comment vos consommateurs utilisent vos données. « Inutilisé » signifie seulement qu'il n'est pas utilisé par vous. Approche sûre : Mesurez l'utilisation des champs en production avant de supprimer quoi que ce soit.

• Restreindre les types d'entrée Passer d'une chaîne (string) à une énumération (enum) ou d'un nombre (number) à un entier (integer) casse les requêtes. Élargir une entrée est sans risque. La restreindre constitue un changement de rupture. Approche sûre : Ne faites qu'assouplir les entrées que vous acceptez. Un durcissement nécessite une nouvelle version.

• Modifier les valeurs par défaut Changer une valeur par défaut de false à true modifie le comportement sans générer d'erreur. Cela casse la logique de manière silencieuse. Approche sûre : Traitez tout changement de valeur par défaut comme un changement de rupture.

• Ajouter des champs obligatoires Ajouter tenantId et le rendre obligatoire casse tous les clients existants. Ils recevront une erreur 400. Approche sûre : Les nouveaux champs doivent être optionnels ou faire l'objet d'une nouvelle version.

• Modifier les formats d'erreur Passer d'un code 400 à un 422 ou modifier le corps de l'erreur casse le code de gestion des erreurs. Approche sûre : Les formats d'erreur sont des contrats. Versionnez-les comme n'importe quel autre élément.

• Modifier les valeurs d'énumération Renommer « active » en « ACTIVE » casse les clients. Supprimer une valeur casse les clients ayant une logique stricte. Approche sûre : Les valeurs d'énumération sont permanentes. Ajoutez-les avec prudence. Ne les renommez ni ne les supprimez jamais sans une version majeure.

• Changer la signification des données Passer d'un format de date en secondes Unix à l'ISO-8601, ou changer la pagination d'un système par décalage (offset) à un système par curseur (cursor), casse tout. Une différence de schéma (schema diff) pourrait même ne pas détecter ces changements. Approche sûre : Fixez les formats explicitement. Comparez les charges utiles (payloads) réelles, pas seulement la spécification.

Ne vous fiez pas à votre intuition. Comparez chaque modification au contrat de production dans votre CI. Un humain pourrait laisser passer un champ renommé. Un outil de diff, non.

Source : https://dev.to/deepaksatyam/9-api-changes-that-look-backwards-compatible-but-arent-1bk0