Gouvernance

Une API vit plus longtemps que le projet qui l’a créée. La gouvernance consiste à décider, avant d’en avoir besoin, comment elle changera et comment elle sera retirée. Tout le reste, conventions, revues, outillage, découle de ces deux décisions.

Le cycle de vie

Conception. Le contrat s’écrit avant l’implémentation, se relit, se publie comme brouillon. Des consommateurs peuvent développer contre un simulacre pendant que le service s’écrit.

Publication. L’API entre en production avec une version, une documentation et un niveau de service annoncé.

Évolution. Les changements compatibles s’accumulent. C’est la phase la plus longue et celle où se prennent les décisions coûteuses.

Dépréciation. L’API fonctionne encore mais ne doit plus être adoptée. Une date de retrait est annoncée. C’est une étape avec une fin, pas un état durable, et la faire durer revient à exploiter deux versions indéfiniment.

Retrait. L’API ne répond plus, de préférence avec un 410 Gone explicite pendant quelques semaines plutôt qu’un silence.

Compatible ou pas

Un changement est compatible s’il ne casse aucun consommateur qui respecte le contrat. Le partage se fait ligne à ligne, pas à l’intuition.

Deux cas de ce tableau surprennent. Une énumération élargie en réponse casse les consommateurs qui traitent les valeurs de façon exhaustive. Le contrat doit dire si la liste est ouverte. Et un champ « ajouté seulement » finit par casser un consommateur qui valide strictement les propriétés inconnues. La policy de validation fait partie du contrat.

La vérification s’outille : un comparateur de contrats en chaîne d’intégration classe chaque modification et bloque les breaking changes non assumés. C’est l’exemple type d’une règle exécutable.

Comment gérer le versioning

La question se pose en trois temps : où porter la version, quand en créer une, et combien en servir à la fois.

Où. Trois emplacements existent, et le choix se fait une fois pour toute la plateforme.

Le chemin gagne en pratique pour une raison d’exploitation : la version apparaît dans les métriques, les journaux et les règles de routage sans traitement particulier. Savoir qui appelle encore la v1 devient une requête au lieu d’un chantier.

Quand. Une version majeure ne se crée que pour un changement incompatible, jamais pour marquer une évolution fonctionnelle. La règle inverse est plus utile encore : la question à se poser n’est pas « faut-il une v2 » mais « ce changement est-il vraiment incompatible », et le tableau ci-dessus y répond. Une bonne partie des v2 publiées auraient pu être des ajouts.

Les versions mineures ne s’exposent pas dans l’URL. Elles se documentent dans le journal des changements et se signalent, si nécessaire, par un en-tête de réponse informatif.

Combien. Une seule version majeure ajoutée à la fois, et jamais plus de deux servies en parallèle. Chaque version en production coûte de l’exploitation, du support et de la surface d’attaque. Une troisième version simultanée n’est pas un choix : c’est le symptôme d’une dépréciation qui n’a pas été menée.

Le cas des API internes. Le versioning coûte cher et se justifie par l’impossibilité de coordonner les consommateurs. En interne, quand les appelants sont connus et joignables, une évolution négociée coûte souvent moins qu’une version de plus à maintenir. Le régime d’exposition décide, voir interne et externe.

La dépréciation, l’étape réellement difficile

Retirer une API demande de savoir qui l’appelle encore, et c’est ici que la gouvernance rejoint l’observabilité : sans métriques par consommateur, la dépréciation se fait à l’aveugle.

La séquence qui fonctionne : annoncer avec la date de retrait, marquer les réponses avec les en-têtes Deprecation et Sunset, contacter nominativement les consommateurs restants sur la base des métriques, réduire progressivement les quotas, retirer. Chaque étape est datée et publique. La difficulté est de tenir le calendrier quand un gros consommateur demande un délai, et c’est une décision de direction, pas de plateforme.

Des règles exécutables

Une règle de gouvernance qui vit dans un document s’applique les six premières semaines. Les règles qui tiennent sont celles que la chaîne vérifie : conventions de nommage, présence des exemples et des descriptions d’erreur, compatibilité des changements, seuils de qualité du contrat. Le document explique le pourquoi, la chaîne applique le quoi.

Ce déplacement change aussi le rôle de l’équipe gouvernance : elle n’examine plus chaque API en comité, elle maintient les règles et leurs exceptions. Les comités d’architecture gardent les cas nouveaux, pas la vérification de conformité.