Chiamare un'API REST con Python e requests: esempi pratici
Come usare la libreria requests per leggere e inviare dati a un'API REST in Python: richieste GET e POST, JSON, autenticazione, errori e tentativi automatici.
Gran parte dei servizi che usiamo ogni giorno, dalle previsioni del tempo ai gestionali aziendali, mette a disposizione i propri dati tramite un'API. Saperla usare da Python permette di automatizzare moltissime attività: scaricare dati, sincronizzare due servizi, pubblicare contenuti, generare report.
In questa guida usiamo requests, la libreria più diffusa per questo scopo, con esempi che puoi eseguire subito su API pubbliche e gratuite.
Cos'è un'API REST, in breve
Un'API (Application Programming Interface) è un modo con cui un programma può chiedere dati o azioni a un altro programma. Le API REST funzionano attraverso il web, con lo stesso protocollo dei siti, l'HTTP. Ci sono pochi concetti da conoscere:
- Endpoint: l'indirizzo a cui si invia la richiesta, per esempio
https://api.esempio.com/clienti. - Metodo: il tipo di operazione. I principali sono
GET(leggere),POST(creare),PUToPATCH(modificare) eDELETE(eliminare). - JSON: il formato di testo con cui di solito si scambiano i dati. In Python diventa un dizionario o una lista.
- Codice di stato: un numero che indica l'esito.
200e201significano successo;4xxindica un errore nella richiesta (per esempio401non autorizzato,404non trovato,429troppe richieste);5xxindica un problema del server.
Installare requests
Come sempre, conviene lavorare dentro un ambiente virtuale. Con l'ambiente attivo:
python -m pip install requests
La prima richiesta GET: le previsioni del tempo
Usiamo Open-Meteo, un servizio meteo gratuito che non richiede registrazione. Chiediamo il meteo attuale a Milano:
import requests
URL = "https://api.open-meteo.com/v1/forecast"
parametri = {
"latitude": 45.46,
"longitude": 9.19,
"current": "temperature_2m,wind_speed_10m",
"timezone": "auto",
}
risposta = requests.get(URL, params=parametri, timeout=10)
risposta.raise_for_status()
dati = risposta.json()
attuale = dati["current"]
print(f"Temperatura: {attuale['temperature_2m']} °C")
print(f"Vento: {attuale['wind_speed_10m']} km/h")
Vediamo le righe importanti:
params: requests aggiunge i parametri all'indirizzo nel formato corretto, gestendo anche spazi e caratteri speciali. Non serve comporre l'URL a mano.timeout=10: se il server non risponde entro 10 secondi, la richiesta si interrompe. Senza timeout, uno script può restare bloccato all'infinito. Mettilo sempre.raise_for_status(): se il codice di stato indica un errore, solleva un'eccezione invece di proseguire con dati sbagliati.json(): trasforma la risposta in un dizionario Python.
Un consiglio pratico: quando lavori con un'API nuova, stampa la risposta completa con print(dati) per vederne la struttura, prima di estrarre i campi che ti interessano.
Inviare dati con una richiesta POST
Per creare qualcosa si usa il metodo POST. Per provare senza rischi usiamo JSONPlaceholder, un servizio di prova che simula un'API reale ma non salva nulla:
import requests
nuovo_articolo = {
"title": "Prova",
"body": "Contenuto di prova",
"userId": 1,
}
risposta = requests.post(
"https://jsonplaceholder.typicode.com/posts",
json=nuovo_articolo,
timeout=10,
)
risposta.raise_for_status()
print(risposta.status_code) # 201: creato
print(risposta.json()) # i dati ricevuti, con l'id assegnato
Il parametro json= converte il dizionario in JSON e imposta da solo l'intestazione Content-Type: application/json. È diverso da data=, che invia i dati come un modulo web: se un'API si aspetta JSON, usa sempre json=.
Autenticazione con un token
Le API private richiedono di identificarsi. Il metodo più comune è un token (o chiave API) inviato nelle intestazioni della richiesta:
import os
import requests
token = os.environ["API_TOKEN"]
intestazioni = {
"Authorization": f"Bearer {token}",
"Accept": "application/json",
}
risposta = requests.get(
"https://api.esempio.com/v1/clienti",
headers=intestazioni,
timeout=10,
)
Nota che il token non è scritto nel codice: viene letto da una variabile d'ambiente. È una regola di sicurezza importante: se il codice finisce su GitHub o viene condiviso, il token resta privato. Per impostare la variabile prima di lanciare lo script:
# Windows, Prompt dei comandi
set API_TOKEN=il-tuo-token
# Windows, PowerShell
$env:API_TOKEN = "il-tuo-token"
# Linux e macOS
export API_TOKEN="il-tuo-token"
Il formato esatto dell'intestazione (Bearer, Token, una chiave in un'intestazione dedicata) dipende dall'API: lo trovi sempre nella sua documentazione.
Gestire gli errori
In uno script reale la rete può non rispondere, il server può essere in manutenzione, il token può scadere. Con un blocco try puoi gestire ciascun caso con un messaggio chiaro:
import requests
try:
risposta = requests.get(URL, params=parametri, timeout=10)
risposta.raise_for_status()
except requests.exceptions.Timeout:
print("Il server non ha risposto in tempo.")
except requests.exceptions.HTTPError as errore:
print(f"Errore HTTP {errore.response.status_code}: {errore.response.text[:200]}")
except requests.exceptions.ConnectionError:
print("Connessione non riuscita: controlla la rete o l'indirizzo.")
else:
dati = risposta.json()
print(dati)
Il blocco else viene eseguito solo se non ci sono stati errori. Stampare una parte del testo della risposta (errore.response.text) è utile, perché molte API spiegano lì il motivo dell'errore.
Sessioni e tentativi automatici
Se lo script fa molte richieste allo stesso servizio, conviene usare una sessione: riutilizza la connessione (ed è quindi più veloce) e permette di impostare una volta sola intestazioni e comportamenti comuni. Con una sessione puoi anche far ripetere automaticamente le richieste fallite per problemi temporanei:
import requests
from requests.adapters import HTTPAdapter
from urllib3.util.retry import Retry
tentativi = Retry(
total=3, # fino a 3 nuovi tentativi
backoff_factor=1, # attese crescenti tra un tentativo e l'altro
status_forcelist=[429, 500, 502, 503, 504],
allowed_methods=["GET"], # ripeti solo le letture
)
sessione = requests.Session()
sessione.mount("https://", HTTPAdapter(max_retries=tentativi))
sessione.headers.update({"User-Agent": "mio-script/1.0"})
risposta = sessione.get(URL, params=parametri, timeout=10)
risposta.raise_for_status()
Perché ripetere solo le richieste GET? Perché leggere due volte non fa danni, mentre ripetere un POST potrebbe creare due volte lo stesso elemento, per esempio due ordini identici.
Buone pratiche
- Imposta sempre un timeout, in ogni richiesta.
- Controlla il codice di stato con
raise_for_status()prima di usare i dati. - Non scrivere mai token e password nel codice: usa variabili d'ambiente.
- Rispetta i limiti dell'API: molte API limitano il numero di richieste. Se ricevi un errore
429, rallenta; alcune indicano nell'intestazioneRetry-Afterquanti secondi aspettare. - Gestisci la paginazione: le API che restituiscono lunghi elenchi li dividono in pagine. La documentazione indica quale parametro usare (per esempio
pageocursor) per chiedere le pagine successive. - Leggi la documentazione dell'API: indirizzi, parametri e formato dell'autenticazione cambiano da un servizio all'altro.
E httpx?
Potresti incontrare anche httpx, una libreria più recente con un'interfaccia molto simile a requests, che supporta anche le richieste asincrone (cioè molte richieste in parallelo). Per script e automazioni requests resta la scelta più semplice; se un giorno ti serviranno le funzioni asincrone, il passaggio a httpx sarà naturale.
Fonti ufficiali
Share
What's Your Reaction?
Like
0
Cancella like
0
Amore
0
Buffo
0
arrabbiato
0
Sad
0
Wow
0