In breve
Un'API (Application Programming Interface) è un modo per due programmi di parlarsi e scambiarsi dati. Invece di un umano che clicca su un sito web, un programma invia una richiesta a un altro programma e riceve una risposta strutturata. Quando la tua applicazione mostra il meteo, invia un'email o interroga un modello di IA, chiama un'API in background. Le API sono le tubature che collegano il software che costruisci al resto del mondo.
L'analogia del ristorante
Vedi un'API come un cameriere. Non vai in cucina a cucinare; dai la tua ordinazione al cameriere, lui la porta in cucina e ti riporta il tuo piatto. L'API è il cameriere: invii una richiesta che descrive ciò che vuoi, e ottieni una risposta, senza mai dover sapere come funziona la cucina all'interno.
Richieste e risposte
Una richiesta parte verso una URL (l'endpoint), spesso con qualche dato allegato. La risposta torna il più delle volte in JSON, un formato di dati strutturato. Il più delle volte il tuo codice o il tuo agente IA gestisce i dettagli, ma la forma è sempre la stessa: chiedi, ricevi una risposta strutturata.
{
"city": "Zurich",
"temperature": 18,
"condition": "cloudy"
}Le chiavi API e perché contano
Molte API richiedono una chiave API, una stringa segreta che ti identifica e spesso pilota la fatturazione. Poiché una chiave può costarti denaro se trapela, va in un file .env e mai in codice committato. È la stessa disciplina dei secret che protegge ogni credenziale del tuo progetto.
Confusioni frequenti dei principianti
Alcuni punti fanno inciampare. Un'API non è un sito web che visiti nel browser; è un servizio a cui il tuo programma parla, e visitare direttamente una URL di API spesso mostra solo dati grezzi o un errore, il che è normale. I "rate limit" sono un'altra sorpresa: molte API limitano il numero di richieste in una finestra di tempo, quindi se delle chiamate falliscono all'improvviso, forse stai solo andando troppo veloce. E diverse API usano regole leggermente diverse di autenticazione e forma della richiesta, per questo leggere la documentazione specifica dell'API conta. La buona notizia: il tuo agente IA legge questi documenti e scrive il codice della richiesta per te, così puoi usare una nuova API con fiducia senza memorizzarne i dettagli in anticipo.