Cos'è un'API e a cosa serve?

Un'API (Application Programming Interface, interfaccia di programmazione delle applicazioni) è il contratto con cui un sistema software espone alcune sue funzioni o alcuni suoi dati ad altri programmi, definendo con esattezza quali richieste accetta, quali risposte restituisce e con quali regole, senza che chi la usa debba sapere come il sistema funziona all'interno. È lo stesso principio della presa elettrica a muro: un elettrodomestico si collega senza conoscere come è fatta la centrale che genera la corrente, purché rispetti la forma della spina e il voltaggio concordati. Quando un software di contabilità chiede il saldo di un conto a una banca, o un sito di e-commerce chiede a un corriere il tracking di una spedizione, la comunicazione passa da un'API: una richiesta in un formato preciso, una risposta in un formato altrettanto preciso, e nessuna delle due parti deve leggere il codice sorgente dell'altra. È il contratto, non l'implementazione, a rendere due sistemi scritti da aziende diverse capaci di parlarsi.

Leggi anche: API gateway · Il punto d'ingresso unico per le API esposte all'esterno: autenticazione, rate limiting, versioning e CORS gestiti fuori dal codice applicativo.

REST, il contratto più diffuso

Lo stile più diffuso per costruire un'API su web è REST (Representational State Transfer): ogni risorsa, un cliente, un ordine, una fattura, ha un proprio indirizzo, e le operazioni su di essa usano i metodi standard del protocollo HTTP, la cui semantica corrente è definita da RFC 9110: GET per leggere, POST per creare, PUT per modificare, DELETE per rimuovere, con codici di risposta (200, 404, 500) che comunicano l'esito senza dover interpretare il corpo della risposta. Esistono alternative come GraphQL e gRPC, ma è lo stile che una PMI incontra quasi sempre integrando un gestionale o un SaaS. Un'API REST si descrive con precisione nella OpenAPI Specification: un fornitore che la pubblica permette di generare automaticamente client, test e documentazione, mentre uno che non la pubblica costringe a scoprire il comportamento dell'API per tentativi.

Webhook contro polling

Chi consuma un'API ha due modi per sapere che è successo qualcosa. Con il polling, il sistema chiamante interroga l'API a intervalli regolari chiedendo se c'è qualcosa di nuovo: semplice da realizzare, ma spreca chiamate quando non c'è nulla e introduce un ritardo pari all'intervallo scelto. Con un webhook, è l'API stessa a chiamare un indirizzo concordato in anticipo nel momento in cui l'evento accade, un pagamento confermato, una spedizione partita: quasi istantaneo, ma richiede un endpoint pubblico sempre raggiungibile e un piano per i messaggi persi se quell'endpoint è offline quando arrivano. La scelta pratica segue l'urgenza: eventi rari o urgenti via webhook, letture frequenti di dati che cambiano poco via polling.

Un esempio concreto

Una PMI vende online e ogni ordine dell'e-commerce deve arrivare nel gestionale per fatturazione e magazzino. Se il gestionale ha API REST documentate e un webhook sul pagamento confermato, l'ordine entra appena il cliente paga e le giacenze aggiornate tornano al sito per la stessa via. Se sa solo esportare e importare file CSV, serve uno script che li carichi a orari fissi: gli ordini arrivano in ritardo, una colonna rinominata blocca l'importazione senza avvisare e gli errori si scoprono a mano.

Perché conta per chi decide

Quando si valuta un nuovo gestionale o un SaaS, oltre al prezzo va chiesto se ha API pubbliche e quanto sono documentate. Senza API pubbliche, ogni integrazione futura, con l'e-commerce, con un CRM, con un cruscotto di reporting, richiede soluzioni di ripiego fragili invece di una connessione diretta, il terreno su cui lavorano un API gateway o un iPaaS. E c'è una parte che si vede solo alla fine del contratto: le stesse API che fanno entrare i dati in un sistema sono spesso le uniche che li fanno uscire il giorno in cui si cambia fornitore, quindi l'assenza di API di lettura pubbliche è un vincolo di strategia di uscita oltre che di integrazione. Lo stesso principio, applicato agli agenti AI, regge protocolli più recenti come MCP.