Quand nommer un champ d’API prend une heure, le problème n’est pas forcément le vocabulaire. L’équipe n’est peut-être pas encore d’accord sur ce que le champ signifie.
J’ai vu des discussions de nommage faire remonter des questions que l’implémentation avait cachées.
Cette valeur est-elle un fait actuel, une demande de changement ou une projection calculée ? Le terme appartient-il au métier, ou seulement à un système interne ? Les clients peuvent-ils s’y fier dans le temps ? Quelle équipe porte la définition quand le processus derrière change ?
Un nom pratique peut clore la réunion sans répondre à aucune de ces questions. L’ambiguïté part alors dans le code des clients, la documentation, le support et les futures migrations.
Le coût arrive plus tard. Un consommateur comprend le champ d’une façon, le producteur voulait dire autre chose, et un incident devient un débat : le payload est-il faux, ou la définition n’a-t-elle jamais été partagée ? Pendant une migration, chaque client emporte sa propre interprétation dans le nouveau système.
C’est pour ça que je traite le nommage comme un travail de contrat, pas comme une finition. Avant de choisir un terme, j’essaie d’écrire une définition en langage courant, un exemple valide et un cas qui ne doit pas rentrer. Si le groupe ne s’accorde pas sur ces trois éléments, aucun nom ne sauvera le design.
La même habitude marche pour les endpoints et les événements. Un contrat doit décrire un concept stable, compréhensible par les consommateurs sans connaître le fonctionnement interne actuel du service.
Un bon nom ne rend pas une API correcte à lui seul. Il rend le désaccord visible tôt, quand changer un champ coûte encore moins cher que de diagnostiquer la même ambiguïté dans chaque intégration.