Septembre 2026

Pathly en API, et un provider Terraform

APICoulisses

Décrire son infrastructure dans des fichiers et créer sa surveillance à la main, c’est entretenir deux vérités qui finissent par diverger. Elle s’écrit maintenant en code : une API documentée, et un provider Terraform.

Le contrat publié est celui qui tourne

L’API sert son propre contrat OpenAPI, sans authentification, à une adresse publique. Ce document n’est pas écrit à côté du code : il est produit à partir de la table qui déclare les routes, celle-là même qui décide, à chaque appel, quelle portée est exigée. Une route qui n’y figure pas ne démarre pas. La page développeurs lit ce contrat au moment du rendu, si bien qu’une route retirée disparaît de la documentation sans que personne y pense. Une documentation recopiée à la main ment toujours, la question est seulement de savoir depuis quand.

• La page développeurs
• Le contrat OpenAPI, au format JSON

Des portées étroites, et quatre refus

Une clé porte des portées de la forme ressource puis action : lire les scénarios, les écrire, déclencher une exécution, clôturer un incident. Écrire implique lire, parce qu’un outil relit toujours ce qu’il vient d’écrire. Déclencher reste séparé de lire, parce qu’une exécution consomme du quota et n’est pas une consultation.

Quatre gestes restent hors d’atteinte d’une clé, par décision et non par oubli. Émettre ou révoquer une clé, parce qu’une clé capable de cela annule les portées de toutes les autres. Inviter un membre, parce que c’est la même chose par un détour : le nouveau compte émettra les clés qu’il veut. Changer d’offre ou toucher à la facturation, parce qu’un jeton d’intégration continue ne doit pas engager de dépense. Exporter l’organisation, parce que l’export contient les membres, donc des données personnelles.

• Émettre une clé et choisir ses portées

Ce qui ne se relit jamais

Un mot de passe d’authentification, l’adresse d’un webhook, les étapes d’un parcours navigateur : ces valeurs s’écrivent et ne ressortent pas. À leur place, l’API rend une empreinte de douze caractères, qui change dès que la valeur change. C’est assez pour qu’un outil détecte qu’une ressource a été modifiée ailleurs, et trop peu pour reconstituer ce qu’elle contient. Terraform s’en sert exactement comme ça : la destination d’un webhook modifiée à la main dans la console se voit au plan suivant, sans que l’adresse soit jamais écrite dans un fichier d’état.

Ce qu’un outil automatique attend d’une API

• Une pagination par curseur, pas par numéro de page : une ressource créée pendant le parcours décalerait les pages, et le client relirait une ligne deux fois ou en sauterait une.
• Un en-tête Retry-After quand le débit est dépassé : sans lui, un client automatisé réessaie à l’aveugle et reste dans sa propre boucle.
• Une clé d’idempotence rejouée pendant vingt-quatre heures : un pipeline relancé après une coupure réseau ne crée pas de doublon.
• Un identifiant appartenant à une autre organisation répond 404, jamais 403 : répondre « interdit » confirmerait son existence.

Le provider

Quatre ressources — un scénario, une fenêtre de maintenance, un webhook, un objectif de disponibilité — et une source de données qui relit l’inventaire, de quoi repérer un scénario créé à la main dans la console et absent du code. Les clés d’API et les membres n’y figurent pas, pour la raison déjà dite : un fichier Terraform qui invite un propriétaire est une escalade par détour.

Deux comportements comptent plus que la liste des ressources. Après un apply, un plan doit être vide : sans cela, l’outil propose une modification à chaque passage et plus personne ne lit ses plans. Et changer l’adresse, l’intervalle ou le seuil de latence d’un scénario doit le modifier en place, jamais le détruire pour le recréer — un scénario recréé perd son historique et ses incidents, c’est-à-dire tout ce pour quoi on le surveillait. Ces deux points ont demandé, côté API, que tout ce qui s’écrit se relise à l’identique. C’est le travail le moins visible du provider, et celui qui décide s’il est utilisable.

Adopter un parc existant

Personne ne recommence sa surveillance de zéro pour passer au code. Chaque ressource s’importe par son identifiant : le scénario créé l’an dernier dans la console entre dans l’état Terraform sans être touché, et le plan suivant montre l’écart entre ce qu’il est et ce que le fichier décrit. C’est la seule manière honnête de migrer, et c’est aussi celle qui permet de revenir en arrière.

Où il en est

Le provider est publié sur le registre public de Terraform, avec sa documentation et ses exemples : une déclaration de version dans un bloc required_providers suffit désormais à l’installer, sans miroir local ni compilation depuis les sources. La numérotation reste en 0.x, ce qui veut dire quelque chose de précis : les ressources existantes ne bougeront pas sans raison, mais nous nous réservons d’ajuster un schéma avant le 1.0. L’API, elle, n’attend pas le provider : une clé, une adresse, et la documentation destinée aux développeurs suffisent pour piloter la même chose depuis n’importe quel langage.