Le breaking change qui ne dit pas son nom

Les breaking changes spectaculaires, suppression d'un endpoint, renommage d'un champ, sont en fait les moins dangereux : tout le monde sait qu'ils cassent, ils passent par une version majeure, les consommateurs sont prévenus.

Les pannes réelles viennent d'ailleurs : de changements que leur auteur croyait anodins. D'abord la règle qui les sépare des vrais changements mineurs, puis l'inventaire, constitué incident après incident.

La ligne de partage

Une seule règle sépare l'anodin du dangereux, et elle se pose en deux questions symétriques. En entrée, tout ce qui restreint casse : un champ obligatoire de plus, une validation resserrée, une valeur d'énumération retirée. En sortie, tout ce qui retire ou modifie casse : un champ supprimé, un type changé, une énumération élargie que le consommateur ne sait pas interpréter.

D'où la réponse à la question la plus fréquente en revue de contrat. Ajouter un champ optionnel en entrée ou un champ en sortie n'est pas un breaking change, à une condition : que les consommateurs ignorent ce qu'ils ne connaissent pas. Cette condition est fausse plus souvent qu'on ne croit, parce qu'un client généré depuis le contrat, ou qui valide strictement la réponse, rejette un champ inattendu. Une API destinée à des clients générés doit donc traiter l'ajout en sortie comme un changement mineur annoncé, pas comme un non-événement.

Les breaking changes qui n'en ont pas l'air

Resserrer une validation. Le champ acceptait 100 caractères, il en accepte désormais 50, « pour être propre ». Tous les consommateurs qui envoyaient 60 caractères reçoivent des 400. Toute validation resserrée est un breaking change, même quand l'ancienne tolérance était un accident.

Corriger une faute dans une énumération. statut: "anulé" devient "annulé". Le correctif orthographique est un breaking change pour tout consommateur qui comparait la valeur.

Changer un défaut. Le tri passe de « date croissante » à « date décroissante », la pagination de 100 à 20 éléments. Aucun schéma ne change, tous les clients qui dépendaient du comportement implicite se comportent différemment. Les défauts font partie du contrat.

Réordonner ou typer autrement le JSON. Un entier qui devient une chaîne ("id": 42 puis "id": "42"), un champ nul qui disparaît au lieu d'être null : selon les parseurs en face, c'est invisible ou fatal. On ne choisit pas les parseurs de ses consommateurs.

Améliorer la latence. Une API qui répondait en 800 ms passe à 80 ms, et un consommateur tombe, parce que sa propre course de concurrence était masquée par la lenteur. Rare, réel, et hors de portée de tout diff de schéma.

Durcir un quota ou un timeout côté gateway. Le breaking change peut venir de la médiation elle-même : la configuration de la plateforme fait partie du contrat vécu par le consommateur, même si elle n'apparaît dans aucun OpenAPI.

Le contrat réel d'une API n'est donc pas son fichier OpenAPI, c'est son comportement observable, défauts et tolérances compris. La revue humaine d'un diff de spécification ne suffit pas : la moitié des breaking changes ci-dessus n'y apparaissent pas.

Les trois automates, du moins cher au plus complet

1. Le diff de contrat en pipeline. Comparer chaque nouvelle version du contrat à la précédente et refuser les changements incompatibles. oasdiff le fait pour OpenAPI et classe lui-même chaque écart en breaking change ou non, avec un code de sortie exploitable en intégration continue. Pour les API en Protobuf, buf breaking remplit le même rôle et le fait mieux, parce que la grammaire s'y prête. Ces outils attrapent les quatre premières lignes de l'inventaire ci-dessus, et aucune des deux dernières.

2. Les tests de contrat pilotés par les consommateurs. Chaque consommateur publie ce qu'il utilise réellement, le fournisseur rejoue ces attentes à chaque build. Pact est l'outillage de référence, et son intérêt n'est pas technique : on n'est plus prévenu que « quelque chose a changé », mais que « l'équipe paiement va casser ». Le passage d'un diff anonyme à un impact nominatif change les conversations. Le coût réel est organisationnel, puisqu'il faut que chaque consommateur publie et maintienne ses attentes.

3. Le miroir de trafic. Rejouer un échantillon du trafic de production contre la version candidate et comparer les réponses. C'est le seul filet qui attrape les breaking changes de comportement absents du schéma, défauts et tolérances compris. Plus coûteux, à réserver aux API dont les consommateurs sont nombreux ou inconnus.

Où placer le contrôle, et comment y déroger

Le diff bloque à la demande de fusion, pas au déploiement. Un contrôle qui échoue au moment de livrer est un contrôle qu'on désactive : l'auteur découvre le problème quand il n'a plus le temps de le traiter, et la première dérogation sauvage devient la coutume.

Prévoyez donc la dérogation avant d'avoir à l'accorder. La forme qui tient est une mention explicite dans la demande de fusion, nominative, avec la liste des consommateurs prévenus. Elle ne demande l'accord de personne et laisse une trace : c'est ce qui la rend utilisable un vendredi soir, et vérifiable le lundi.

Quand le breaking change est assumé

Il arrive qu'on doive casser. Le sujet devient alors la fenêtre laissée aux consommateurs, et elle se signale dans le protocole plutôt que dans un courriel.

Deux en-têtes normalisés existent pour cela. Deprecation, standardisé en mars 2025, porte la date à laquelle la ressource est ou sera dépréciée. Sunset porte la date à laquelle elle cessera de répondre, jamais antérieure à la première. Les deux sont lisibles par un automate, ce qui permet de mesurer combien de consommateurs appellent encore une ressource condamnée, et à quelle vitesse ce nombre baisse.

C'est le seul indicateur qui dise si la dépréciation avance. La règle de fenêtre elle-même, selon la nature du consommateur, et la mécanique de versionnage qui va avec sont traitées dans la gouvernance.

Le coût de l'absence

Sans automate, chaque breaking change silencieux se découvre en production, chez le consommateur, avec un diagnostic à l'aveugle : son équipe cherche chez elle, puisque « l'API n'a pas changé de version ». Comptez les heures des deux côtés, multipliez par la fréquence des livraisons, et le diff de contrat en pipeline devient probablement l'investissement au meilleur rendement de toute votre chaîne APIOps.