Salta ai contenuti

16. Client robusti

  • Mettere un timeout a ogni richiesta e sapere cosa fare quando scatta.
  • Ritentare solo quando ha senso (rete, 429, 5xx), con attese crescenti e rispettando Retry-After.
  • Validare le risposte con un modello (pydantic / zod) invece di fidarsi del JSON.
  • Registrare X-Request-Id per rintracciare una chiamata nei log del server.
  • Capire l’idempotenza: quali richieste puoi ripetere senza paura.

Un client “che funziona” nella demo e un client robusto in produzione si distinguono in cinque punti.

Senza timeout una richiesta può restare appesa per minuti (server bloccato, rete che perde pacchetti). httpx senza timeout usa 5 secondi; fetch non ha timeout di default. Regola: un timeout esplicito, dell’ordine dei secondi, ovunque.

Non tutti gli errori meritano un nuovo tentativo:

Errore Ritentare? Perché
timeout, connessione rifiutata, DNS sì transitorio
429 sì, dopo Retry-After il server ti ha detto quando
500, 502, 503, 504 sì, poche volte il server (o il proxy) sta avendo problemi
400, 401, 403, 404, 409, 422 no ripetere la stessa richiesta dà lo stesso risultato: va cambiato qualcosa

L’attesa tra i tentativi cresce (backoff esponenziale: 0.5 s, 1 s, 2 s, 4 s) con un po’ di casualità (jitter), così mille client che falliscono insieme non riprovano tutti nello stesso istante.

r.json() restituisce “qualcosa”. Un modello (pydantic in Python, zod in TypeScript) trasforma quel qualcosa in un oggetto con campi noti e tipi verificati: se l’API cambia o risponde una cosa inattesa, l’errore scatta subito e vicino alla causa, non tre funzioni più in là con un KeyError o un undefined. Nella Sezione 1 (capitoli 7 e 8) hai visto gli strumenti; qui li usi al confine tra la tua applicazione e il mondo.

Ogni risposta del server di prova ha un X-Request-Id. Se lo metti nei tuoi log (e negli errori che mostri), puoi chiedere “cos’è successo alla richiesta c759f5c4d347?” e chi gestisce il server può cercarla. Le API serie fanno tutte così (X-Request-Id, X-Amzn-RequestId, cf-ray…).

Una richiesta è idempotente se farla due volte ha lo stesso effetto di farla una: GET, PUT (sostituisce), DELETE (cancellare due volte = cancellato), PATCH con valori assoluti ({"price": 12}). POST non lo è: se il tuo retry ripete un POST /orders andato a buon fine ma la cui risposta si è persa, hai due ordini. Per questo il retry automatico è sicuro solo su richieste idempotenti; per i POST servono una chiave di idempotenza (header Idempotency-Key, che molte API di pagamento supportano) o un controllo prima di ripetere.

curl stesso ha le opzioni per un uso robusto:

terminale
curl -s --connect-timeout 5 --max-time 15 \
--retry 3 --retry-delay 1 --retry-all-errors \
-w '\nstatus=%{http_code} tempo=%{time_total}s\n' \
-D - https://corso-api-json.giuseppebosi.com/api/v1/books/7 | grep -i 'x-request-id\|^{\|status='
--connect-timeout 5
massimo 5 secondi per aprire la connessione
--max-time 15
massimo 15 secondi per l'intera richiesta, risposta inclusa
--retry 3
fino a 3 nuovi tentativi su errori transitori (curl di suo considera 429, 500, 502, 503, 504 e i timeout)
--retry-delay 1
attesa fissa di 1 s tra i tentativi (senza, curl usa un backoff che raddoppia: 1, 2, 4… s)
--retry-all-errors
ritenta anche su altri errori HTTP e di rete. Attenzione: su un POST può duplicare!
%{time_total}
tempo totale della richiesta, in secondi
grep …
mostra solo x-request-id, il body JSON e la riga di riepilogo
x-request-id: 3eff19594867
{"id":7,"title":"Oltre Trieste",…}
status=200 tempo=0.06s

Per una PATCH (idempotente) il retry è sicuro: curl --retry 3 -X PATCH … -d '{"price": 19.9}'. Per una POST no: usa --retry solo se l’API supporta una chiave di idempotenza.

Una classe LibreriaClient completa: connessione riusata, timeout, retry con backoff e Retry-After, errori tipizzati con X-Request-Id, risposte validate, paginazione automatica.

# pip install httpx pydantic → python3 client.py
import logging
import random
import time
import httpx
from pydantic import BaseModel
BASE = "https://corso-api-json.giuseppebosi.com/api/v1"
log = logging.getLogger("libreria")
logging.basicConfig(level=logging.INFO, format="%(levelname)s %(message)s")
class Book(BaseModel): # solo i campi che ci servono: il resto viene ignorato
id: int
title: str
price: float
author_id: int
in_stock: bool
class ApiError(Exception):
def __init__(self, status: int, code: str, message: str, request_id: str | None):
super().__init__(f"{status} {code}: {message} (request {request_id})")
self.status, self.code, self.request_id = status, code, request_id
class LibreriaClient:
"""Client con timeout, retry con backoff esponenziale e tipizzazione delle risposte."""
def __init__(self, base: str = BASE, token: str | None = None, timeout: float = 10.0, retries: int = 4):
headers = {"Authorization": f"Bearer {token}"} if token else {}
self.http = httpx.Client(base_url=base, timeout=timeout, headers=headers) # riusa la connessione
self.retries = retries
def _request(self, method: str, path: str, **kw) -> httpx.Response:
for tentativo in range(self.retries + 1):
try:
r = self.http.request(method, path, **kw)
except httpx.TransportError as e: # rete giù, timeout: ritenta
if tentativo == self.retries:
raise
attesa = 0.5 * 2**tentativo + random.uniform(0, 0.3)
log.warning("%s %s: %s, ritento tra %.1fs", method, path, e, attesa)
time.sleep(attesa)
continue
if r.status_code == 429 or r.status_code >= 500:
if tentativo == self.retries:
break
attesa = float(r.headers.get("Retry-After", 0.5 * 2**tentativo))
log.warning("%s %s -> %s, ritento tra %.1fs", method, path, r.status_code, attesa)
time.sleep(attesa)
continue
if r.is_error: # 4xx: non ritentare, spiegare
err = r.json().get("error", {})
raise ApiError(r.status_code, err.get("code", "error"), err.get("message", r.text), r.headers.get("X-Request-Id"))
return r
raise ApiError(r.status_code, "retry_exhausted", "troppi tentativi", r.headers.get("X-Request-Id"))
def book(self, book_id: int) -> Book:
return Book.model_validate(self._request("GET", f"/books/{book_id}").json())
def books(self, **filtri) -> list[Book]:
"""Scorre tutte le pagine e restituisce la lista completa."""
out, page = [], 1
while True:
data = self._request("GET", "/books", params={**filtri, "page": page, "limit": 100}).json()
out += [Book.model_validate(b) for b in data["items"]]
if not data["links"]["next"]:
return out
page += 1
def set_price(self, book_id: int, price: float) -> Book:
# PUT/PATCH sono idempotenti: ripeterli in caso di dubbio non fa danni
return Book.model_validate(self._request("PATCH", f"/books/{book_id}", json={"price": price}).json())
if __name__ == "__main__":
pubblico = LibreriaClient()
print(pubblico.book(7))
economici = pubblico.books(max_price=10, sort="price")
print(f"{len(economici)} libri sotto i 10 €; il primo: {economici[0].title}")
try:
pubblico.book(9999)
except ApiError as e:
print("gestito:", e)
token = httpx.post(f"{BASE}/sandbox").json()["token"]
privato = LibreriaClient(token=token)
print("nuovo prezzo:", privato.set_price(7, 19.9).price)

Cosa dovresti vedere:

id=7 title='Oltre Trieste' price=28.25 author_id=12 in_stock=False
9 libri sotto i 10 €; il primo: La cucina di Ferrara
gestito: 404 not_found: Libro 9999 non trovato (request 662ef848ca6b)
nuovo prezzo: 19.9
INFO HTTP Request: GET https://corso-api-json.giuseppebosi.com/api/v1/books/7 "HTTP/1.1 200 OK"
INFO HTTP Request: GET https://corso-api-json.giuseppebosi.com/api/v1/books?max_price=10&sort=price&page=1&limit=100 "HTTP/1.1 200 OK"
INFO HTTP Request: GET https://corso-api-json.giuseppebosi.com/api/v1/books/9999 "HTTP/1.1 404 Not Found"
INFO HTTP Request: POST https://corso-api-json.giuseppebosi.com/api/v1/sandbox "HTTP/1.1 201 Created"
INFO HTTP Request: PATCH https://corso-api-json.giuseppebosi.com/api/v1/books/7 "HTTP/1.1 200 OK"

Nota che Book ignora i campi che non ha dichiarato (isbn, attributes, reviews_count…): il tuo codice dipende solo da ciò che usa, e l’API può aggiungere campi senza romperlo. Se invece un campo dichiarato manca o cambia tipo, model_validate/parse lo segnala subito.

Osserva x-request-id negli header di ogni risposta: è il valore da mettere nei log.

GET/api/v1/books/7— richiesta con X-Request-Id
GET/api/v1/books/9999— 404: da non ritentare

Provalo online, senza installare nulla:

Apri il notebook in Google Colab Apri il progetto TypeScript in StackBlitz

La richiesta GET diretta nel browser: https://corso-api-json.giuseppebosi.com/api/v1/books/7

Python su Google Colab (serve un account Google gratuito per eseguire le celle); TypeScript su StackBlitz (si apre e parte da solo nel browser). Se l’API di prova è spenta, accendila da /api-attiva/.

  1. Aggiungi al client un metodo create_order(...) che non ritenta su errori di rete (perché?) ma ritenta su 429.
  2. Metti timeout=0.001 e osserva cosa succede: quale eccezione, quanti tentativi, quanto tempo totale?
  3. Aggiungi un log di una riga per ogni richiesta con metodo, path, status, millisecondi e X-Request-Id.
Soluzione
  1. POST /orders non è idempotente: se la risposta si perde dopo che l’ordine è stato creato, un retry ne crea un secondo. Su 429 invece il server garantisce di non aver eseguito la richiesta, quindi ritentare è sicuro. Implementazione: un parametro retry_network: bool in _request, False per i POST.
  2. httpx.ConnectTimeout / TimeoutError di AbortSignal, 5 tentativi (1 + 4 retry) con attese 0.5, 1, 2, 4 s: circa 7,5 s più il jitter, poi l’eccezione dell’ultimo tentativo.
  3. In _request, prima del return r: log.info("%s %s %s %.0fms id=%s", method, path, r.status_code, r.elapsed.total_seconds()*1000, r.headers.get("X-Request-Id")) (in TS misura con performance.now()).
  • fetch senza AbortSignal.timeout: può aspettare per sempre.
  • Ritentare i 4xx: sprechi tempo e richieste, e con 409/422 non cambierà nulla.
  • Retry immediati e fissi (sleep(1) sempre): tutti i client si risincronizzano sui picchi. Backoff + jitter.
  • Un client nuovo per ogni chiamata: niente keep-alive, e i limiti di connessioni del sistema operativo si esauriscono.
  • Non salvare X-Request-Id negli errori: quando serve, non c’è più.

Timeout ovunque, retry solo su errori transitori con backoff e Retry-After, risposte validate da un modello, X-Request-Id nei log, e retry automatici solo su richieste idempotenti. Hai in mano un client da produzione. Nel prossimo capitolo lo usi per il progetto finale: sincronizzare il catalogo in un database locale e gestire un ordine dall’inizio alla fine.