Versionner les interfaces : comment changer sans casser
Ce qui compte comme changement cassant
Supprimer un champ ou une route, changer un type, rendre obligatoire un champ optionnel, changer la signification d'une valeur existante et resserrer les limites. Ajouter un champ optionnel ne casse pas — tant que les consommateurs ignorent les champs qu'ils ne reconnaissent pas, une règle qui mérite d'être documentée.
Comment gérer une transition
Faites tourner la nouvelle version à côté de l'ancienne, mesurez qui utilise encore l'ancienne, et éteignez-la seulement après que l'utilisation a atteint zéro ou que vous avez donné assez de préavis.
Peu de versions avec un contenu significatif valent mieux qu'une version par petit changement. Chaque version vivante est du code à maintenir et à tester.
Déprécier progressivement
Marquez les champs et les routes comme destinés à la suppression dans la documentation et dans un en-tête de réponse, avec une date. Envoyez un avis aux consommateurs actifs. Et enfin, avant d'éteindre — effectuez une « obscurité contrôlée » : coupez quelques minutes et voyez qui crie.
Pour aller plus loin
Conservez des métriques par version et par consommateur, pas seulement par route. Sans cela, éteindre une ancienne version est un pari, et celui qui est touché le découvrira dans sa production — c'est-à-dire dans un appel urgent qui vous parvient.