Glossario

API (Application Programming Interface)

Un'API (Application Programming Interface) è un insieme di regole che permette a un programma di chiedere dati o funzioni a un altro programma, senza conoscerne il codice interno. Definisce quali richieste sono ammesse e in quale formato arriva la risposta. È il modo con cui software diversi si collegano e si scambiano informazioni.

Cos’è un’API e come funziona

Un’API funziona come il menù di un ristorante: elenca cosa si può ordinare e come chiederlo, mentre la cucina resta fuori vista. Un programma invia una richiesta in un formato concordato, di solito tramite il protocollo HTTP, e riceve una risposta, spesso in JSON.

Chi usa l’API non deve sapere come il servizio è costruito: gli basta rispettare il contratto, cioè l’indirizzo da chiamare, i parametri da inviare, la risposta attesa e, se serve, la chiave di accesso.

A cosa serve un’API

  • Collegare il gestionale al sito e-commerce senza inserire due volte gli stessi dati.
  • Mostrare in una pagina mappe, meteo o sistemi di pagamento forniti da un’altra azienda.
  • Far dialogare un’app mobile con il server che custodisce i dati.
  • Usare un modello di intelligenza artificiale dentro un software proprio.
  • Automatizzare operazioni tra servizi diversi, senza interventi manuali.

Tipi di API: REST, GraphQL e SOAP

Le più diffuse sono le API REST, che usano gli indirizzi web e i metodi HTTP. GraphQL lascia a chi chiama la scelta dei campi da ricevere, e riduce i dati trasferiti inutilmente. SOAP è un protocollo più rigido basato su XML, ancora presente nei sistemi aziendali più datati.

API pubbliche, private e di partner

Le API pubbliche sono aperte a qualunque sviluppatore, di solito dopo una registrazione. Le API private restano dentro l’azienda e collegano i suoi sistemi. Quelle di partner sono riservate a soggetti con cui esiste un accordo, come un fornitore o un cliente.

Autenticazione e sicurezza di un’API

Un’API si protegge con una chiave o con un token di accesso, spesso ottenuto con il protocollo OAuth 2.0, e si usa sempre su connessione cifrata HTTPS. I fornitori impongono anche un limite di richieste al minuto, per evitare abusi e sovraccarichi.

Documentazione e versioni di un’API

La documentazione elenca gli indirizzi disponibili, i parametri e le risposte possibili. Molte API la descrivono con lo standard OpenAPI. Le versioni numerate (v1, v2) permettono al fornitore di cambiare l’API senza rompere le integrazioni già in funzione.

Come si prova un’API

Una richiesta si può inviare dalla riga di comando con curl, oppure con un programma grafico come Postman, e si controllano codice di stato e contenuto della risposta. Un’API in produzione si monitora: si misurano tempi di risposta, errori e numero di richieste. I fornitori dichiarano di solito un livello di servizio, detto SLA, che indica la disponibilità promessa.

Com’è fatta una richiesta a un’API

Una richiesta contiene l’indirizzo da chiamare, il metodo HTTP che indica l’operazione, le intestazioni con informazioni aggiuntive, come la chiave di accesso e il formato dei dati, e a volte un corpo con i dati da inviare. La risposta riporta un codice di stato, per esempio 200 se è andato tutto bene o 404 se la risorsa non esiste, le sue intestazioni e un corpo con il risultato, di solito in JSON. Conoscere questi elementi serve a leggere la documentazione e a capire perché una chiamata fallisce.

Webhook e richieste periodiche

Per sapere che qualcosa è cambiato in un altro sistema ci sono due strade. Con le richieste periodiche, dette polling, il programma interroga l’API a intervalli regolari e confronta i dati. Con un webhook succede il contrario: è il servizio a chiamare un indirizzo indicato dall’azienda nel momento in cui si verifica un evento, come un pagamento ricevuto o un ordine spedito. Il webhook riduce il traffico e i ritardi, ma richiede che l’indirizzo sia raggiungibile da internet e protetto con una verifica della firma del messaggio.

Come integrare un’API nei processi aziendali

Il lavoro parte dalla documentazione e dalle credenziali di un ambiente di prova, detto sandbox, dove si fanno i test senza toccare dati reali. Nel programma vanno gestiti gli errori e i tempi di attesa: se la chiamata fallisce si riprova con intervalli crescenti, e se continua a fallire si registra l’anomalia. Conviene salvare un registro delle chiamate, controllare i limiti di richieste e i costi, e seguire gli annunci del fornitore sui cambi di versione. Un’integrazione crea una dipendenza, quindi si valuta in anticipo che cosa succede se il servizio si ferma o cambia le condizioni.

Limiti di richieste e gestione delle quote

La maggior parte delle API fissa un numero massimo di richieste per minuto o per giorno. Superata la soglia, il servizio risponde con il codice 429 e spesso indica nell’intestazione Retry-After quanto attendere. Un programma ben scritto rispetta il limite, ripete le richieste fallite con attese crescenti e non lancia migliaia di chiamate in parallelo. Quando il traffico previsto supera la quota gratuita, si passa a un piano a pagamento o si riducono le chiamate, ad esempio salvando in una cache le risposte che cambiano di rado.

Fonti e approfondimenti