Pila
Il problema che volevo risolvere
Avevo bisogno di un modo affidabile di raccogliere, pulire e strutturare dati business provenienti da molte fonti caotiche, poi di trasmetterli ad altri strumenti in una forma prevedibile. Il mio primo riflesso, come la maggior parte delle persone, e stato costruire un bel dashboard. Ho cominciato dagli schermi. E l'errore che mi ha insegnato di piu.
Perche sono passato all'API-First
Lungo la strada, ho realizzato che ogni consumatore di questi dati era un programma, non un umano che clicca su pulsanti: un'automazione, uno scraper, un altro agente, un futuro io che scrive uno script a mezzanotte. L'UI era un sottile aggiunta a posteriori. Ho quindi ricostruito tutto attorno a una API documentata, con il dashboard come semplice client di questa API piuttosto che come il prodotto stesso.
- Ogni capacita e un endpoint con un contratto stabile, non un pulsante sepolto in uno schermo.
- L'API viene fornita con uno spec OpenAPI, perche un agente possa scoprirla e usarla senza che io spieghi qualsiasi cosa.
- Le risposte sono JSON prevedibile, sempre della stessa forma, perche i consumatori non debbano mai indovinare.
Cosa e cambiato quando l'API e passata prima
Dall'istante in cui l'API e diventata il prodotto, tutto cio che seguiva e diventato piu semplice. Le automazioni si collegavano senza scrapare schermi. I test sono diventati banali, perche testavo endpoint, non percorsi di click. E quando ho lanciato un agente IA sullo spec OpenAPI, ha saputo usare BizCollect correttamente al primo colpo, perche il contratto gli diceva esattamente cosa inviare e cosa ricevere. E stato il clic: uno strumento che un'IA puo capire e pilotare senza che gli si tenga la mano vale molto di piu nel 2026 di uno strumento in cui solo un umano puo navigare.
Cosa farei diversamente
Scriverei lo spec OpenAPI prima di scrivere il minimo endpoint, e lo tratterei come un documento di progettazione. Versionerei anche l'API dal primo giorno, invece di aggiungere il versionamento piu tardi. Il dashboard, lo si puo sempre rigenerare; un contratto di API rotto rompe tutti quelli che dipendono da te, inclusi agenti che non hai mai incontrato.
Lezioni apprese
- Progetta l'API prima dell'UI. L'API e il prodotto; l'UI e solo uno dei suoi client.
- Pubblica un contratto leggibile dalla macchina (OpenAPI), perche gli agenti usino il tuo strumento senza che un umano traduca la doc.
- Risposte prevedibili e identiche battono le risposte astute. I consumatori non dovrebbero mai dover gestire sorprese.
- In un mondo Agent-First, "l'IA puo pilotarlo senza sorveglianza" e una vera feature, non un bonus.