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.

Chiamare un'API REST con Python e requests: esempi pratici

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), PUT o PATCH (modificare) e DELETE (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. 200 e 201 significano successo; 4xx indica un errore nella richiesta (per esempio 401 non autorizzato, 404 non trovato, 429 troppe richieste); 5xx indica 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'intestazione Retry-After quanti secondi aspettare.
  • Gestisci la paginazione: le API che restituiscono lunghi elenchi li dividono in pagine. La documentazione indica quale parametro usare (per esempio page o cursor) 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 Like 0
Cancella like Cancella like 0
Amore Amore 0
Buffo Buffo 0
arrabbiato arrabbiato 0
Sad Sad 0
Wow Wow 0