Settembre 2026

Pathly come API, e un provider Terraform

APIDietro le quinte

Descrivere la propria infrastruttura in file e creare il monitoraggio a mano significa mantenere due verità che finiscono per divergere. Ora si scrive in codice: un’API documentata e un provider Terraform.

Il contratto pubblicato è quello che gira

L’API serve il proprio contratto OpenAPI, senza autenticazione, a un indirizzo pubblico. Questo documento non è scritto a parte rispetto al codice: è generato dalla tabella che dichiara le rotte, la stessa che decide, a ogni chiamata, quale ambito è richiesto. Una rotta che non vi figura non si avvia. La pagina per sviluppatori legge questo contratto al momento del rendering, così una rotta rimossa scompare dalla documentazione senza che nessuno ci pensi. Una documentazione copiata a mano mente sempre, la domanda è solo da quando.

• La pagina per sviluppatori
• Il contratto OpenAPI, in formato JSON

Ambiti ristretti, e quattro rifiuti

Una chiave porta ambiti nella forma risorsa poi azione: leggere gli scenari, scriverli, avviare un’esecuzione, chiudere un incidente. Scrivere implica leggere, perché uno strumento rilegge sempre ciò che ha appena scritto. Avviare resta separato da leggere, perché un’esecuzione consuma quota e non è una consultazione.

Quattro operazioni restano fuori dalla portata di una chiave, per scelta e non per dimenticanza. Emettere o revocare una chiave, perché una chiave capace di farlo annulla gli ambiti di tutte le altre. Invitare un membro, perché è la stessa cosa per una via traversa: il nuovo account emetterà le chiavi che vuole. Cambiare piano o toccare la fatturazione, perché un token di integrazione continua non deve impegnare spese. Esportare l’organizzazione, perché l’esportazione contiene i membri, quindi dati personali.

• Emettere una chiave e sceglierne gli ambiti

Ciò che non si rilegge mai

Una password di autenticazione, l’indirizzo di un webhook, i passaggi di un percorso nel browser: questi valori si scrivono e non tornano indietro. Al loro posto, l’API restituisce un’impronta di dodici caratteri, che cambia appena cambia il valore. Basta perché uno strumento rilevi che una risorsa è stata modificata altrove, ed è troppo poco per ricostruirne il contenuto. Terraform la usa esattamente così: la destinazione di un webhook modificata a mano nella console si vede al plan successivo, senza che l’indirizzo venga mai scritto in un file di stato.

Cosa si aspetta uno strumento automatico da un’API

• Una paginazione a cursore, non a numero di pagina: una risorsa creata durante la lettura sposterebbe le pagine, e il client rileggerebbe una riga due volte o ne salterebbe una.
• Un’intestazione Retry-After quando il limite di richieste è superato: senza di essa, un client automatico riprova alla cieca e resta chiuso nel proprio ciclo.
• Una chiave di idempotenza riprodotta per ventiquattro ore: una pipeline riavviata dopo un’interruzione di rete non crea duplicati.
• Un identificativo che appartiene a un’altra organizzazione risponde 404, mai 403: rispondere «vietato» ne confermerebbe l’esistenza.

Il provider

Quattro risorse — uno scenario, una finestra di manutenzione, un webhook, un obiettivo di disponibilità — e una fonte di dati che rilegge l’inventario, quanto basta per individuare uno scenario creato a mano nella console e assente dal codice. Le chiavi API e i membri non ci sono, per il motivo già detto: un file Terraform che invita un proprietario è un’escalation per via traversa.

Due comportamenti contano più dell’elenco delle risorse. Dopo un apply, un plan deve essere vuoto: altrimenti lo strumento propone una modifica a ogni passaggio e nessuno legge più i suoi plan. E cambiare l’indirizzo, l’intervallo o la soglia di latenza di uno scenario deve modificarlo sul posto, mai distruggerlo per ricrearlo — uno scenario ricreato perde la sua cronologia e i suoi incidenti, cioè tutto ciò per cui lo si monitorava. Questi due punti hanno richiesto, lato API, che tutto ciò che si scrive si rilegga identico. È il lavoro meno visibile del provider, ed è quello che decide se è utilizzabile.

Adottare un parco esistente

Nessuno ricomincia il proprio monitoraggio da zero per passare al codice. Ogni risorsa si importa tramite il suo identificativo: lo scenario creato l’anno scorso nella console entra nello stato Terraform senza essere toccato, e il plan successivo mostra lo scarto tra ciò che è e ciò che il file descrive. È l’unico modo onesto di migrare, ed è anche quello che permette di tornare indietro.

A che punto è

Il provider è pubblicato sul registro pubblico di Terraform, con la sua documentazione e i suoi esempi: una dichiarazione di versione in un blocco required_providers ora basta per installarlo, senza mirror locale né compilazione dai sorgenti. La numerazione resta in 0.x, e questo significa qualcosa di preciso: le risorse esistenti non cambieranno senza motivo, ma ci riserviamo di modificare uno schema prima della 1.0. L’API, invece, non aspetta il provider: una chiave, un indirizzo e la documentazione per sviluppatori bastano per gestire le stesse cose da qualsiasi linguaggio.