« On va mettre nos APIs dans Git. » La phrase revient dans presque toutes les démarches d'industrialisation que nous accompagnons, quelle que soit la passerelle : produit d'éditeur, solution open source ou service managé d'un cloud provider. L'intention est bonne. Mais entre l'intention et un dépôt qui sert vraiment de source de vérité, il y a une série de choix que l'on regrette de ne pas avoir faits au début.

Cet article rassemble ces choix. Il ne dépend d'aucun produit : les mêmes questions se posent sur toutes les passerelles et plateformes d'intégration que nous avons rencontrées.

Le piège de départ : versionner l'export de la console

La première tentative ressemble souvent à ceci : on exporte la configuration depuis la console d'administration, on la pousse dans Git, et on considère le sujet traité. Trois problèmes apparaissent vite :

  • l'export n'est pas fait pour être relu : formats binaires ou JSON de plusieurs milliers de lignes, champs générés, horodatages qui changent à chaque export ;
  • il contient des identifiants propres à un environnement : un export de recette ne se rejoue pas tel quel en production ;
  • il embarque parfois des valeurs sensibles : mots de passe de backend, clés, certificats.

Un dépôt où chaque diff fait trois cents lignes de bruit n'est pas relu. Et un dépôt qui n'est pas relu n'est pas une source de vérité, c'est une sauvegarde.

Ce qu'on met dans le dépôt

La règle que nous appliquons : on versionne l'intention, pas l'état technique. Concrètement, un dépôt d'API contient quatre familles de fichiers.

1. Le contrat

La spécification de l'interface : OpenAPI pour le REST, WSDL pour le SOAP, AsyncAPI pour les flux événementiels. C'est le document le plus important, parce que c'est lui que les consommateurs voient. Il se relit comme du code, se valide automatiquement (lint, règles de style) et se compare d'une version à l'autre pour détecter les ruptures.

2. La description des politiques

Authentification exigée, limites de trafic, routage, transformations : décrits dans un format lisible, aussi indépendant que possible du format interne de la passerelle. L'objectif est qu'un relecteur comprenne ce qui change en lisant le diff, sans connaître la console.

C'est la couche de déploiement qui traduit cette description dans le format propre à la passerelle. Cette séparation a un bénéfice inattendu : le jour où l'on change de passerelle, l'intention est déjà écrite.

3. Les valeurs par environnement

URL des backends, alias, quotas, noms de certificats : un fichier par environnement, dans un format simple. Ces fichiers ne contiennent que ce qui varie réellement d'un environnement à l'autre. Si un fichier d'environnement ressemble à une copie du contrat, c'est que la séparation est mal faite.

4. La version visée par environnement

Un fichier qui dit « en recette, version 2.3 ; en production, version 2.2 ». Promouvoir une API, c'est modifier ce fichier par une merge request. L'historique Git répond alors directement à la question « qu'est-ce qui tournait en production tel jour ? ».

Ce qu'on n'y met jamais

  • Les secrets. Pas de mot de passe, pas de clé privée, pas de jeton, même chiffré « temporairement ». On versionne une référence (le nom du secret dans le coffre-fort), et la valeur est lue au moment du déploiement. Un secret poussé une fois dans l'historique Git doit être considéré comme exposé et renouvelé : le supprimer dans un commit suivant ne l'efface pas de l'historique.
  • Les identifiants techniques générés par la passerelle. Ils changent d'un environnement à l'autre et d'une réinstallation à l'autre. Le pipeline les résout au déploiement.
  • Les données d'exploitation. Statistiques, journaux, états d'activation transitoires : ce n'est pas de la configuration.
  • Les artefacts produits par le pipeline. Archives d'export, paquets, fichiers générés : ils se reconstruisent à partir du dépôt et se stockent, si besoin, dans un dépôt d'artefacts.

Un dépôt par API, ou un dépôt pour tout ?

Il n'y a pas de bonne réponse universelle. Ce que nous observons :

  • un dépôt par API ou par domaine donne des droits fins (chaque équipe gère ses APIs), des historiques lisibles et des pipelines rapides ;
  • un dépôt central facilite les changements transverses (une politique commune à toutes les APIs) et la vue d'ensemble, mais les droits et les revues deviennent plus lourds ;
  • un compromis fréquent : un dépôt par domaine pour les APIs, et un dépôt de socle pour les politiques communes et les modèles, consommé par les autres.

Le critère décisif est organisationnel : qui relit, qui approuve, qui est réveillé en cas d'incident. La structure du dépôt doit suivre la structure des responsabilités.

Branches, tags et promotion

Nous recommandons un modèle simple :

  • une branche principale protégée, sur laquelle on ne pousse que par merge request relue ;
  • un tag par version publiée du contrat ;
  • la promotion entre environnements par modification du fichier de version visée, pas par une branche par environnement.

Le modèle « une branche par environnement » paraît intuitif, mais il produit vite des branches qui divergent et des fusions risquées. Une seule histoire, des versions taguées, et un fichier qui dit quelle version va où : c'est plus facile à auditer.

Détecter la dérive

Versionner dans Git ne sert à rien si quelqu'un peut encore modifier la production à la main sans que personne ne le voie. Deux mécanismes complètent le dispositif :

  • une relecture de l'état réel après chaque déploiement, comparée à l'état attendu ;
  • un contrôle périodique de dérive, qui compare l'environnement au dépôt et signale tout écart, même sans déploiement.

La fréquence de contrôle et le délai de traitement des écarts se définissent avec les équipes, selon chaque contexte.

Par où commencer

  1. Choisir une API représentative et écrire son contrat proprement, s'il n'existe pas déjà sous une forme exploitable.
  2. Décrire ses politiques et ses valeurs d'environnement dans des fichiers séparés.
  3. Écrire la couche de déploiement pour une seule passerelle et deux environnements hors production.
  4. Ajouter la relecture après déploiement, puis le contrôle de dérive.
  5. Seulement ensuite, généraliser.

Le plus difficile n'est pas technique : c'est d'obtenir que plus personne ne modifie la configuration en dehors du dépôt. C'est pour cela que la structure doit être assez simple pour que la voie Git soit aussi la voie la plus facile.

À côté du conseil, CAB Ingénierie édite STOA, iPaaS souverain, plateforme d'API et d'intégration.

Parlons de votre projet

Vous voulez faire de Git la source de vérité de vos APIs, ou votre dépôt actuel ne joue plus ce rôle ? Décrivez-nous votre contexte en quelques lignes : cab-ingenierie.com · contact@cab-ingenierie.com