Cos'è un'API REST
Un'API (Application Programming Interface) è un'interfaccia che permette a due software di comunicare tra loro. REST (Representational State Transfer) è lo stile architetturale più diffuso per le API web: usa il protocollo HTTP, è stateless (ogni richiesta è indipendente) e scambia dati in formato JSON.
Nel contesto dell'AI, le API REST sono il modo standard per accedere a modelli linguistici, di embedding, di visione e di generazione senza doverli eseguire in locale. Provider come OpenAI, Anthropic, Google e Cohere espongono i loro modelli tramite API che chiunque può integrare nelle proprie applicazioni.
Punti chiave
- Una API REST usa HTTP, è stateless e scambia dati in JSON: è il modo standard per usare l'AI senza eseguire i modelli in locale.
- Le richieste a un LLM viaggiano in POST verso un endpoint, con parametri come
model,messages,temperatureemax_tokens. - L'autenticazione avviene tramite API key nell'header
Authorization: mai metterle nel codice, sempre in variabili d'ambiente. - I provider applicano rate limit (RPM e TPM): gestire gli errori 429 con retry e backoff esponenziale è essenziale in produzione.
- OpenAI e Anthropic offrono interfacce simili ma con differenze concrete su system prompt, struttura dei messaggi e funzionalità avanzate.
Le API democratizzano l'accesso all'AI: non servono GPU da migliaia di euro o competenze di infrastruttura ML. Una semplice richiesta HTTP e sufficiente per sfruttare i modelli piu potenti al mondo.
HTTP methods e endpoint
Le API REST usano i metodi HTTP standard per le diverse operazioni:
| Metodo | Azione | Esempio AI |
|---|---|---|
| GET | Leggere una risorsa | Elencare i modelli disponibili |
| POST | Creare/inviare dati | Inviare un prompt e ricevere la risposta |
| PUT | Aggiornare una risorsa | Aggiornare un dataset di fine-tuning |
| DELETE | Eliminare una risorsa | Eliminare un modello fine-tunato |
Un endpoint è l'URL specifico che espone una funzionalità. Per le API AI, gli endpoint principali sono: completions (generazione di testo), embeddings (vettorizzazione), images (generazione immagini) e fine-tuning (addestramento personalizzato).
Nella pratica quotidiana, chi integra l'AI in un prodotto usa quasi sempre il metodo POST verso l'endpoint di chat: è qui che si invia il prompt e si riceve la risposta del modello. GET serve invece per attività di gestione (elencare i modelli, controllare lo stato di un job di fine-tuning), mentre PUT e DELETE entrano in gioco solo quando si amministrano risorse persistenti come dataset o file caricati.
Capire la distinzione tra i metodi aiuta anche a leggere la documentazione dei provider: ogni endpoint indica quale verbo HTTP accetta e quale struttura di payload si aspetta. Per un'applicazione di marketing — ad esempio un generatore di testi o un assistente che risponde ai clienti — nel 90% dei casi basta padroneggiare bene la singola chiamata POST verso le chat completions.
Request e response JSON
Le API AI scambiano dati in formato JSON (JavaScript Object Notation). Una richiesta tipica a un LLM include il modello, i messaggi e i parametri di generazione:
Struttura della request
{"model": "gpt-4o", "messages": [{"role": "system", "content": "Sei un assistente."}, {"role": "user", "content": "Cos'e il machine learning?"}], "max_tokens": 500, "temperature": 0.7}
Parametri chiave della richiesta:
- model: quale modello usare (gpt-4o, claude-sonnet-4-20250514, gemini-1.5-pro).
- messages: la conversazione, con ruoli system/user/assistant.
- temperature (0-2): controlla la casualità. 0 = deterministico, 1+ = creativo.
- max_tokens: limite massimo di token nella risposta.
- top_p: nucleus sampling, alternativa alla temperature.
La response contiene la risposta generata, i metadati (ID, modello usato) e le informazioni di utilizzo (token consumati per input e output), fondamentali per monitorare i costi.
Saper leggere il campo usage della risposta è una competenza pratica spesso trascurata: moltiplicando i token di input e output per il prezzo del modello si calcola il costo esatto di ogni chiamata. In un progetto reale questo permette di stimare in anticipo quanto costerà, ad esempio, generare mille descrizioni prodotto o rispondere a un certo volume di richieste clienti. Impostare un max_tokens adeguato e un prompt conciso è il modo più diretto per tenere i costi sotto controllo.
Autenticazione e API key
Le API AI richiedono un'API key per identificare l'utente, tracciare l'utilizzo e addebitare i costi. La key viene inviata nell'header HTTP Authorization:
Authorization: Bearer sk-xxxxxxxxxxxxxxxx
Sicurezza delle API key
Mai inserire API key nel codice sorgente o in repository Git.
Usa variabili d'ambiente: OPENAI_API_KEY, ANTHROPIC_API_KEY.
Ruota le key periodicamente e limita i permessi al minimo necessario.
Monitora l'utilizzo nella dashboard del provider per rilevare abusi.
Alcuni provider offrono autenticazione avanzata con OAuth 2.0 per applicazioni che agiscono per conto di utenti terzi, ma per l'uso diretto delle API le API key restano lo standard.
Rate limiting e gestione errori
I provider impongono limiti di utilizzo (rate limit) per garantire la stabilita del servizio. I limiti si applicano tipicamente su due dimensioni: richieste per minuto (RPM) e token per minuto (TPM).
Codici di errore comuni:
- 401 Unauthorized: API key mancante o non valida.
- 429 Too Many Requests: rate limit superato. Implementa retry con backoff esponenziale.
- 500 Internal Server Error: problema lato server. Riprova dopo qualche secondo.
- 400 Bad Request: parametri non validi (es. prompt troppo lungo per la context window).
La best practice e implementare un sistema di retry con exponential backoff: attendere 1s, poi 2s, poi 4s tra i tentativi, fino a un massimo di 3-5 retry. Librerie come tenacity in Python semplificano questa logica.
Esempio: API OpenAI
OpenAI offre l'ecosistema API piu maturo, con endpoint per chat completions, embeddings, immagini (DALL-E), audio (Whisper, TTS) e fine-tuning.
Chiamata base con Python
from openai import OpenAI
client = OpenAI()
response = client.chat.completions.create(model="gpt-4o", messages=[{"role": "user", "content": "Ciao!"}])
print(response.choices[0].message.content)
Funzionalita avanzate: function calling (il modello puo invocare funzioni definite dall'utente), streaming (risposte token per token per ridurre la latenza percepita), vision (analisi di immagini) e JSON mode (output strutturato garantito).
Esempio: API Anthropic
Anthropic offre API per la famiglia Claude con un'interfaccia simile ma con differenze nella struttura dei messaggi e nelle funzionalita specifiche:
Chiamata base con Python
import anthropic
client = anthropic.Anthropic()
message = client.messages.create(model="claude-sonnet-4-20250514", max_tokens=1024, messages=[{"role": "user", "content": "Ciao!"}])
print(message.content[0].text)
Differenze chiave rispetto a OpenAI: il system prompt e un parametro separato (non un messaggio), il content e strutturato come lista di blocchi (testo, immagini), supporto nativo per contesti molto lunghi (fino a 200K token).
Le API REST sono il ponte tra i modelli AI e le applicazioni reali. Che si tratti di un chatbot, di un sistema RAG o di un pipeline di analisi dati, la competenza nell'uso delle API e la skill pratica piu richiesta per chi lavora con l'AI. Per iniziare a programmare, consulta Python per l'AI.
Vuoi imparare ad applicarlo davvero?
Scopri i corsi e la formazione di Federico Boggia su AI, dati e digitale.