Cos’è un’API in parole semplici (per chi usa Cursor e ChatGPT)

Un’API è un modo standard per far parlare due programmi. Ecco cos’è in parole semplici — con esempi da Cursor e ChatGPT, senza diagrammi inutili.

Se stai creando piccoli script o siti con l’aiuto dell’intelligenza artificiale — Cursor, Claude, ChatGPT — ti imbatti quasi subito in questa sigla. Chiedi le previsioni del tempo e l’IA risponde: «certo, chiamiamo l’API del meteo». Chiedi di riassumere un testo e ti propone uno script che «fa una richiesta all’API di OpenAI».

API (Application Programming Interface) sembra un concetto da corso di informatica, spesso spiegato con nuvole, frecce e rettangoli inutili.

In realtà un’API non è un pezzo di ferro, non è «il cloud» e non è un’app con icona. È un contratto: il modo standard in cui due programmi si scambiano informazioni o si chiedono favori, senza un umano che clicchi ogni volta.

In questo articolo ti mostro cos’è davvero in parole semplici, come la vedi nel vibe coding, come leggere il codice che l’IA ti genera e quali errori di sicurezza evitare per primi.

---

Cos’è un’API: la definizione operativa

Un’API non è un’applicazione che apri. Non è un database. Non serve «avere un server» per usarla: dal tuo portatile puoi consumare migliaia di API pubbliche.

L’analogia del ristorante resta la più chiara.

Sei al tavolo. In cucina ci sono cuochi, frigo, ricette (il sistema di chi offre il servizio). Vuoi un piatto: non entri in cucina a cucinare. Ti serve un menu (cosa puoi chiedere) e un cameriere (chi porta l’ordine in un formato standard e riporta il risultato).

In questa analogia:

• Tu = il programma che ha bisogno di un dato (client)
• La cucina = il sistema remoto (server / servizi dietro)
• Menu + cameriere = l’API

L’API espone un set definito di richieste: «se mi mandi un messaggio scritto così, faccio il lavoro sporco e ti restituisco questo tipo di risultato».

Due programmi non devono conoscersi dall’interno. Il tuo script Python su Windows o Mac può parlare con un server scritto in un altro linguaggio dall’altra parte del mondo — basta rispettare il contratto.

---

Un esempio quotidiano: l’app del meteo

L’app meteo sul telefono non possiede satelliti. Ha un’interfaccia. Dietro le quinte, quando chiedi il tempo a Matera:

1. Richiesta — l’app prepara un messaggio: «previsioni per queste coordinate, prossimi 3 giorni».
2. Viaggio — lo invia via internet all’API di un servizio meteo.
3. Elaborazione — il server controlla il formato, interroga i suoi dati, confeziona la risposta.
4. Risposta — torna testo strutturato (non grafica): pioggia, probabilità, temperatura.
5. Visualizzazione — l’app legge i dati e disegna la nuvola.

Senza API, l’app dovrebbe contenere tutto il database mondiale (impossibile) oppure tu andresti a leggere tabelle a mano. L’API è il ponte.

---

Il vocabolario minimo delle API

Quando Cursor o ChatGPT ti scrivono codice, usano queste parole. Non serve diventare ingegnere: serve riconoscerle.

---

HTTP: la lingua franca delle API moderne

Esistono tanti modi per far parlare due programmi. Nel 99% dei casi di web e script Python assistiti dall’IA incontri API REST su HTTP.

HTTP è la stessa lingua del browser: digiti un indirizzo e premi Invio. Le API usano la stessa infrastruttura, ma invece di HTML e bottoni restituiscono dati crudi — quasi sempre JSON.

Oltre all’endpoint serve l’azione (metodo HTTP). I due che vedi di continuo:

• GET — leggere / recuperare dati («che tempo fa?», «lista articoli»). Non crea risorse.
• POST — creare o inviare un payload («pubblica commento», «traduci questo testo con l’IA»).

Gli endpoint sono URL. Per scomporre protocollo, host, path e query: Cosa c’è dentro un URL.

---

Dove vedi le API in Cursor e ChatGPT

Nel vibe coding non scrivi quasi mai HTTP a mano. L’IA genera blocchi che usano librerie del linguaggio per «chiamare l’API».

Caso tipico. Chiedi a ChatGPT: «script Python che legge una barzelletta a caso da internet e la stampa».

Otterrai qualcosa del genere:

import requests

# 1. Endpoint (indirizzo dell'API)
url = "https://official-joke-api.appspot.com/random_joke"

# 2. Richiesta GET
risposta = requests.get(url)

# 3. Da testo a oggetto utilizzabile
dati_json = risposta.json()

# 4. Estrai e stampa
print("Ecco la barzelletta:")
print(dati_json["setup"])
print(dati_json["punchline"])

Cosa succede:

1. requests si comporta come un client HTTP.
2. Va all’url, fa un GET (solo lettura), salva il risultato in risposta.
3. risposta.json() trasforma il testo in struttura (dizionario) da cui estrarre setup e punchline.

In JavaScript sul sito, l’IA userà spesso fetch() invece di requests. La logica resta: invia → aspetta → converti JSON → estrai.

const url = "https://official-joke-api.appspot.com/random_joke";

const risposta = await fetch(url);
const dati = await risposta.json();

console.log(dati.setup);
console.log(dati.punchline);

---

API Key: il badge di accesso (e perché va protetto)

Le API pubbliche (barzellette, meteo base) spesso non chiedono chi sei. Quelle professionali — OpenAI, Anthropic, Stripe… — costano risorse. Non possono accettare milioni di richieste anonime.

Entra in gioco l’API Key: una lunga stringa che funziona come badge + carta di credito. La alleghi alla richiesta (di solito in un header). Il server controlla la chiave, i permessi e il credito; se manca o è sbagliata → 401 Unauthorized.

🚨 Avviso critico — Non pubblicare mai le API Key
Chi ha la tua chiave può spendere a tue spese. Bot scansionano GitHub e chat pubbliche in pochi secondi.
Mai così:

# MODO SBAGLIATO (vulnerabile)
api_key = "sk-ESEMPIO-NON-REALE-NON-FARLO"

La chiave non vive nel codice sorgente. Chiedi all’IA di usare un file .env (variabili d’ambiente) e di non committarlo. Per il panorama delle falle tipiche nel codice generato: 7 falle di sicurezza comuni nel codice generato dall’IA.

---

Laboratorio pratico: un’API nel browser

Non fidarti sulla parola: intercetta una chiamata vera con i DevTools.

Prerequisito: browser desktop (Chrome, Edge o Firefox) su Windows, macOS o Linux.

Passi

1. Apri una nuova scheda (ancora senza navigare).
2. Apri gli strumenti sviluppatore:
   • Windows / Linux: F12 oppure Ctrl + Shift + I
   • macOS: Cmd + Option + I
3. Vai alla scheda Network (Rete).
4. Nel filtro, seleziona Fetch/XHR (nasconde immagini/font/CSS e lascia le chiamate dati).
5. Naviga su un sito moderno che carica dati in dinamico (quotidiano, dashboard, feed).
6. Il pannello si riempie di righe: ogni riga è spesso una chiamata API.
7. Clicca una riga e guarda:
   • Headers — Request URL (endpoint), Method (GET/POST), Status (200…);
   • Response / Preview — quasi sempre JSON con {} e [].

Hai appena visto una conversazione client ↔ API.

💡 Consiglio pratico
Se vedi stringhe lunghe tipo token o cookie di sessione, non fare screenshot pubblici e non condividerli. Per il lab basta capire struttura e status code.

---

Errori tipici nel vibe coding

1. Confondere API e libreria (SDK)

Chiedi «chiama l’API di OpenAI» e l’IA fa import openai. L’SDK è codice locale che formatta JSON e HTTP per te. L’API è il servizio remoto. Maggiordomo (SDK) vs cameriere/menu (API).

2. Ignorare i rate limit

Anche con chiave valida, mille richieste al secondo finiscono in 429 Too Many Requests. Se l’IA scrive un for serrato, chiedi: «aggiungi una pausa (sleep) tra le chiamate».

3. Scontrarsi con il CORS

In Python locale chiami quasi ogni API. Lo stesso fetch in una pagina HTML aperta nel browser può fallire con errore «CORS policy»: il browser blocca origini diverse finché il server non autorizza. Non chiedere all’IA di «disattivare CORS in locale» come soluzione seria. Guida dedicata: CORS troppo aperti nelle API IA: come rimuovere l’asterisco.

---

Checklist: hai capito le API se…

• Sai che l’API non è un’app grafica, ma un menu di regole tra macchine.
• Distingui endpoint (dove) e metodo (cosa fare: GET/POST…).
• Riconosci il JSON come formato tipico di risposta.
• Tratti l’API Key come password: mai in chiaro nel repo.

Con questi punti gestisci la maggior parte delle conversazioni con Cursor/ChatGPT su integrazioni e dati.

---

Domande Frequenti (FAQ)

Cos’è un’API in parole semplici?

Un contratto digitale tra due programmi: quali richieste puoi fare, come formattarle e come sarà la risposta. Come un cameriere tra te e la cucina.

Che differenza c’è tra un’API e un sito web o un’app?

Sito e app sono per umani (pulsanti, layout). Un’API è per macchine: dati e testo strutturato, senza abbellimenti.

Cosa significa «chiamare un’API»?

Far eseguire al tuo codice (o farlo generare all’IA) l’invio di una richiesta formattata a un server remoto e l’attesa della risposta.

Cos’è un’API Key e perché non va condivisa?

Una stringa segreta che identifica il tuo account. I servizi a consumo addebitano le richieste: chi ha la chiave può spendere i tuoi fondi. Mai nel codice pubblico.

Devo saper programmare per capire le API?

No. Richiesta, endpoint, JSON e chiave sono concetti di architettura. Cursor/ChatGPT scrivono spesso il codice; tu guidi, controlli e tieni i segreti al sicuro.

Cos’è JSON in questo contesto?

Il formato testuale standard delle risposte API moderne: elenchi di chiavi e valori (es. "nome": "Alex"), comodo per macchine e leggibile anche da te.

Perché a volte ricevo 401 o 429?

401 = non autorizzato (chiave assente/sbagliata/scaduta). 429 = troppe richieste in poco tempo (rate limit). Controlla header della chiave e rallenta i cicli.

---

Prossimi passi utili già sul sito: anatomia dell’URL, 7 falle nel codice IA, CORS e l’asterisco.