Le mot « gouvernance » fait souvent fuir les équipes de développement, et on les comprend. Dans beaucoup d'organisations, il désigne un comité mensuel, un document de normes de plusieurs dizaines de pages que personne n'a lu en entier, et un formulaire à remplir avant toute publication. Résultat : les règles sont contournées, ou appliquées de façon inégale, et la gouvernance devient un frein sans être une garantie.
Il existe une autre approche, que nous mettons en œuvre quelle que soit la passerelle ou la plateforme d'intégration : peu de règles, vérifiées automatiquement, au moment du déploiement.
Ce que la gouvernance doit vraiment garantir
Avant d'écrire la moindre règle, il faut se demander ce que l'on cherche à éviter. Dans la plupart des contextes, la liste tient en quelques lignes :
- une API exposée sans authentification ;
- une API dont personne ne sait qui est responsable ;
- un changement qui casse les consommateurs sans prévenir ;
- une API en production qui ne correspond pas à ce qui a été validé ;
- des données sensibles exposées sans que personne ne l'ait décidé.
Tout le reste (conventions de nommage, style des chemins, format des dates) est utile, mais secondaire. Le confondre avec l'essentiel est la première cause d'usine à gaz.
Principe 1 : une règle qui n'est pas vérifiée automatiquement n'existe pas
Une norme écrite dans un document n'est appliquée que lorsque quelqu'un s'en souvient. Nous transformons chaque règle importante en contrôle automatique exécuté par le pipeline de déploiement :
- le contrat (OpenAPI, WSDL ou AsyncAPI) est validé par un linter avec un jeu de règles versionné ;
- la description des politiques est vérifiée : authentification présente, limite de trafic définie, responsable renseigné ;
- le contrat est comparé à la version précédente pour détecter les ruptures de compatibilité.
Ces contrôles sont du code, versionnés, relus et testés comme le reste. On parle souvent de policy-as-code : le terme importe peu, l'essentiel est que la règle s'exécute.
Principe 2 : refuser plutôt que constater
Un tableau de bord qui liste les APIs non conformes en production arrive trop tard : l'API est déjà exposée. Nous plaçons les contrôles critiques avant le déploiement, et le pipeline refuse de déployer une API qui ne les respecte pas. C'est ce qu'on appelle un fonctionnement fail-closed : en cas de doute, on bloque.
Cela suppose deux garde-fous :
- les règles bloquantes doivent être peu nombreuses et indiscutables, sinon les équipes chercheront à contourner le pipeline ;
- il faut une procédure d'exception explicite, tracée et limitée dans le temps, plutôt qu'une désactivation silencieuse du contrôle.
Les règles moins critiques peuvent rester en avertissement : elles apparaissent dans la merge request, sans bloquer.
Principe 3 : la conformité se vérifie aussi après coup
Un déploiement conforme ne garantit pas que la production le reste. Une modification manuelle en console, un correctif d'urgence ou une dérive de configuration peuvent faire diverger l'environnement de ce qui a été validé. D'où deux contrôles complémentaires :
- après chaque déploiement, relire l'état réel et le comparer à l'état attendu ;
- périodiquement, comparer l'ensemble de l'environnement au dépôt et signaler tout écart.
Une API dont la définition en production ne correspond plus à ce qui a été validé n'est plus gouvernée, même si elle l'était le jour de sa mise en service.
Principe 4 : la responsabilité est une donnée, pas une case
« Qui est responsable de cette API ? » est la question que l'on se pose au pire moment, en plein incident. Nous rendons ce champ obligatoire dans la description de chaque API, avec une équipe et un moyen de contact, et le pipeline refuse une API sans responsable. C'est une règle simple, peu coûteuse, qui rend de grands services.
Principe 5 : les ruptures de contrat se négocient avant, pas après
Un changement incompatible (champ supprimé, type modifié, chemin renommé) n'est pas interdit, mais il doit être visible et assumé :
- le pipeline détecte la rupture en comparant le contrat à la version précédente ;
- une rupture impose une nouvelle version majeure, ou une approbation explicite ;
- l'ancienne version reste disponible pendant une période de transition annoncée.
Nous recommandons une période de transition définie avec les équipes, selon le contexte.
À quoi ressemble le jeu de règles de départ
Pour démarrer, nous proposons généralement un socle court :
- bloquant : authentification déclarée sur toute API exposée ;
- bloquant : responsable renseigné ;
- bloquant : contrat valide syntaxiquement ;
- bloquant : pas de rupture de compatibilité sans version majeure ou approbation ;
- bloquant : aucune valeur sensible en clair dans le dépôt ;
- avertissement : conventions de nommage et de style ;
- avertissement : documentation des codes d'erreur.
Ce socle s'enrichit avec le temps, à partir des incidents réels plutôt que de normes théoriques.
Le rôle qui reste aux humains
Automatiser les contrôles ne supprime pas le besoin de décisions humaines. Il les déplace là où elles ont de la valeur : la relecture des merge requests par un pair, l'arbitrage des exceptions, l'évolution du jeu de règles. Un comité peut garder un rôle, mais pour faire évoluer les règles, pas pour valider chaque API une par une.
Ce qu'il faut retenir
Une gouvernance d'API efficace tient en peu de règles, vérifiées par le pipeline, bloquantes quand l'enjeu le justifie, avec une procédure d'exception assumée et un contrôle de dérive en production. C'est moins spectaculaire qu'un référentiel complet, mais c'est appliqué à chaque déploiement, sans exception silencieuse. Et cela fonctionne sur n'importe quelle passerelle, parce que les règles portent sur le contrat et l'intention, pas sur le produit.
À côté du conseil, CAB Ingénierie édite STOA, iPaaS souverain, plateforme d'API et d'intégration.
Parlons de votre projet
Votre gouvernance d'API est restée sur le papier, ou au contraire elle ralentit tout le monde ? Décrivez-nous votre contexte en quelques lignes : cab-ingenierie.com · contact@cab-ingenierie.com