C'è un pattern che si ripete spesso nei progetti software che arrivano da noi dopo un primo sviluppo fatto altrove. Il sistema funziona, fa quello per cui è stato costruito, ma a un certo punto l'azienda ha bisogno di collegarlo a qualcos'altro: un CRM, un gestionale, una piattaforma e-commerce, uno strumento di analytics. Ed è lì che iniziano i problemi.
Non perché le integrazioni siano impossibili, ma perché il software non è stato progettato pensando a quel momento. Aggiungere un'API a posteriori su un sistema che non l'ha mai prevista è un po' come cercare di installare le porte in un edificio già costruito: si può fare, ma costa molto più che averle messe in fase di progetto.
L'approccio API-first nasce esattamente da questa consapevolezza.
Cosa significa, concretamente, API-first
API-first non è una tecnologia, è un modo di impostare la progettazione. Significa che prima di scrivere la prima riga di codice si definisce come il sistema comunicherà con il mondo esterno: quali dati espone, in che formato, con quale struttura, con quali regole di accesso.
L'API, in questo approccio, non è un componente aggiunto alla fine. È il contratto attorno a cui si costruisce tutto il resto. Il frontend, il backend, le integrazioni con sistemi terzi: tutto parte da quella definizione condivisa.
In pratica, questo si traduce spesso nell'uso di specifiche standard come OpenAPI (ex Swagger), che permettono di documentare e validare le API in modo leggibile sia dagli sviluppatori che dagli strumenti automatici. Prima ancora di avere un sistema funzionante, si ha già una descrizione precisa di come si comporterà. Questo permette a team diversi di lavorare in parallelo, al frontend di svilupparsi contro una specifica anche quando il backend non è ancora pronto, e al cliente di capire cosa sta comprando.
Perché chi commissiona software dovrebbe interessarsene
È facile capire perché l'approccio API-first interessa agli sviluppatori. Ma ha ricadute molto concrete anche per chi commissiona un software senza scrivere codice.
La prima riguarda la flessibilità futura. Un sistema progettato API-first è molto più semplice da integrare con nuovi strumenti. Cambia il CRM? Si aggiorna il connettore. Si aggiunge un canale di vendita? Si collega all'API esistente. Si vuole esporre i dati a un partner commerciale? Esiste già una struttura per farlo. Ogni integrazione futura parte da una base solida invece che da zero.
La seconda riguarda il vendor lock-in, che abbiamo già discusso in un articolo precedente. Un sistema con API ben definite e documentate è più portabile. I dati sono accessibili in modo strutturato, le logiche di business sono esposte in modo standard. Se un giorno si decide di cambiare il frontend, aggiungere un'app mobile, o migrare parte del sistema su una piattaforma diversa, l'API è il punto di continuità che rende tutto più gestibile.
La terza è più sottile ma importante: la qualità del software. Progettare un'API costringe a ragionare sulla struttura dei dati e sulle responsabilità dei vari componenti molto prima di quanto si farebbe altrimenti. È un esercizio di chiarezza che spesso fa emergere ambiguità nel progetto quando è ancora economico risolverle, invece che dopo mesi di sviluppo.
Il problema delle integrazioni aggiunte dopo
Per capire cosa si perde rinunciando all'approccio API-first, vale la pena descrivere l'alternativa. È quello che succede quando un sistema viene sviluppato come applicazione chiusa, con tutte le logiche concentrate internamente, e le integrazioni vengono aggiunte man mano che servono.
Il risultato, dopo qualche anno, è spesso un sistema con una serie di connettori costruiti in momenti diversi, da persone diverse, con approcci diversi. Uno usa un formato di dati, un altro ne usa un altro. Uno autentica le richieste in un modo, un altro in modo diverso. La documentazione, se esiste, è frammentata o già obsoleta.
Ogni nuova integrazione diventa un progetto a sé, perché non c'è una base comune da cui partire. I tempi si allungano, i costi crescono, e il rischio di introdurre errori aumenta perché si lavora su un sistema che nessuno conosce completamente.
Non è una situazione rara. È lo stato naturale di molti software aziendali che hanno qualche anno di vita e sono cresciuti per aggiunta progressiva senza una visione architetturale di fondo.
API-first nell'ecosistema e-commerce
Un contesto in cui l'approccio API-first ha avuto un impatto particolarmente visibile è l'e-commerce. Il modello tradizionale prevedeva piattaforme monolitiche in cui tutto, dal catalogo prodotti al checkout, dalla gestione degli ordini al layer di presentazione, viveva nello stesso sistema.
Il problema è che questi monoliti faticano ad adattarsi alla velocità con cui cambiano i canali di vendita e le aspettative dei clienti. Aggiungere un canale social, integrare un marketplace, costruire un'app mobile: su un monolite ogni aggiunta è costosa e rischiosa.
Il headless commerce, che separa il frontend dal backend tramite API, è la risposta diretta a questo problema ed è un'evoluzione naturale dell'approccio API-first applicato all'e-commerce. Il backend gestisce catalogo, ordini, pagamenti e logistica e li espone tramite API. Il frontend, che sia un sito, un'app, un chiosco fisico o un assistente vocale, consuma quelle API e si occupa solo della presentazione. I due livelli possono evolvere indipendentemente.
Non è la soluzione giusta per tutti. Per un piccolo e-commerce con esigenze standard, un approccio headless introduce complessità non necessaria. Ma per realtà che hanno bisogno di flessibilità su più canali, è spesso la scelta che evita di dover ricostruire tutto tra qualche anno.
Come si applica in un progetto reale
Nella pratica, adottare un approccio API-first in un progetto richiede alcune scelte precise fin dall'inizio.
La prima è definire le specifiche API prima di iniziare lo sviluppo, usando uno standard come OpenAPI. Questo documento diventa il riferimento condiviso per tutto il team e per il cliente. Cambiarlo ha un costo, il che incoraggia a ragionarci bene prima.
La seconda è separare chiaramente il backend, che contiene le logiche di business e i dati, dal frontend, che si occupa della presentazione. Anche in progetti di dimensioni contenute questa separazione paga nel tempo.
La terza è versionare le API. Quando un'API cambia, i sistemi che la usano devono adattarsi. Avere un sistema di versioning chiaro (v1, v2, e così via) permette di evolvere l'API senza rompere le integrazioni esistenti, dando ai consumatori il tempo di aggiornarsi.
In Redergo questo approccio è parte del modo in cui progettiamo i sistemi, in particolare quando il cliente sa già, o può ragionevolmente prevedere, che il software dovrà integrarsi con altri strumenti nel tempo. Non è una complessità aggiuntiva: è un investimento che si ripaga alla prima integrazione che non diventa un progetto da capo.
La domanda da fare prima di iniziare
C'è una domanda semplice che vale la pena porre all'inizio di qualsiasi progetto software: questo sistema dovrà mai parlare con qualcos'altro?
La risposta è quasi sempre sì, anche se non si sa ancora con cosa. I software aziendali non vivono in isolamento. Si connettono a strumenti di contabilità, a piattaforme di marketing, a sistemi di spedizione, a portali clienti. Prima o poi.
Partire da questa consapevolezza cambia le decisioni architetturali fin dall'inizio. E le decisioni prese all'inizio sono quelle che costano di meno da fare bene e di più da correggere dopo.
