14. Performance, cache, rate limit
Obiettivi
Sezione intitolata “Obiettivi”- Usare
ETageIf-None-Matchper non riscaricare ciò che non è cambiato (304). - Leggere
Cache-Controle capire cosa può essere messo in cache e da chi. - Vedere la compressione all’opera e sapere chi la applica.
- Riusare la connessione TCP/TLS (keep-alive) invece di aprirne una per richiesta.
- Riconoscere
429 Too Many Requests+Retry-Aftere comportarsi bene.
Un’API veloce è fatta di tre cose: non fare lavoro inutile (cache), trasferire meno byte (compressione), non ripagare costi fissi (connessioni). E di una quarta: proteggersi da chi ne abusa (rate limit), perché la lentezza di uno diventa la lentezza di tutti.
ETag e richieste condizionali
Sezione intitolata “ETag e richieste condizionali”Un ETag (entity tag) è un’impronta della risposta, ad esempio l’hash del JSON. Il server la manda nell’header ETag; alla richiesta successiva il client la rimanda in If-None-Match. Se la risorsa è identica, il server risponde 304 Not Modified senza body: pochi byte invece di tutto il documento. Il client usa la copia che aveva.
Cache-Control
Sezione intitolata “Cache-Control”Dice chi può conservare la risposta e per quanto:
| Valore | Significato |
|---|---|
public, max-age=60 |
chiunque (browser, proxy, CDN) può tenerla 60 secondi |
private, max-age=… |
solo il browser dell’utente, non i proxy condivisi |
no-cache |
conservabile, ma da rivalidare (con ETag) prima di riusarla |
no-store |
non conservare mai (dati personali, risposte con token) |
Sul server di prova solo GET /books/{id} senza token risponde public, max-age=60; tutto il resto (liste, statistiche, e qualsiasi richiesta con il token) è no-store: la tua sandbox è tua.
Compressione
Sezione intitolata “Compressione”Con Accept-Encoding: gzip, zstd il client dichiara cosa sa decomprimere; il server (o il reverse proxy davanti a esso) comprime e risponde Content-Encoding: gzip. Il JSON si comprime molto bene (spesso 5-10 volte). Qui la compressione la fa l’API stessa (GZipMiddleware di FastAPI), quindi la vedi anche in locale con uvicorn da solo: /books?limit=100 passa da circa 29.500 a 4.100 byte. In produzione davanti c’è Caddy, che può sostituirla con zstd.
Keep-alive
Sezione intitolata “Keep-alive”Aprire una connessione HTTPS costa: handshake TCP + TLS, decine di millisecondi e qualche round-trip. HTTP/1.1 tiene la connessione aperta (keep-alive) e la riusa per le richieste successive; HTTP/2 le multiplexa. Il client deve però riusare lo stesso oggetto (httpx.Client, un’istanza di fetch con agent condiviso): chiamate “usa e getta” aprono una connessione ogni volta.
Rate limit
Sezione intitolata “Rate limit”Il server conta le richieste per indirizzo IP in una finestra di tempo; oltre la soglia risponde 429 Too Many Requests con Retry-After: <secondi>. Un client educato aspetta quel tempo e riprova; uno maleducato insiste e resta bloccato più a lungo. Il limite del server di prova pubblico è 30 richieste al minuto per IP (120 in locale).
curl, spiegato opzione per opzione
Sezione intitolata “curl, spiegato opzione per opzione”ETag e 304
Sezione intitolata “ETag e 304”curl -s -D - -o /dev/null https://corso-api-json.giuseppebosi.com/api/v1/books/7- -D -
- dump-header: scrive gli header della risposta su un file;
-= sullo standard output - -o /dev/null
- butta via il body: vogliamo vedere solo gli header
HTTP/1.1 200 OKcontent-type: application/jsonetag: "02956e4cbf57f15a"cache-control: public, max-age=60x-request-id: 1728fff735c5Ora la stessa richiesta dichiarando “ho già la versione con questo ETag”:
curl -s -D - -o /dev/null https://corso-api-json.giuseppebosi.com/api/v1/books/7 \-H 'If-None-Match: "02956e4cbf57f15a"'- -H 'If-None-Match: "…"'
- l'ETag va rimandato con le virgolette: fanno parte del valore. Per questo l'header è tra apici singoli
HTTP/1.1 304 Not Modifiedetag: "02956e4cbf57f15a"Niente body: la tua copia è ancora buona. Se nel frattempo il libro cambia (in sandbox: un PATCH), l’ETag cambia e torni a ricevere 200 con il JSON.
Con il token la stessa richiesta risponde cache-control: no-store: prova con curl -s -D - -o /dev/null … -H "Authorization: Bearer $TOKEN" | grep -i cache.
Compressione
Sezione intitolata “Compressione”curl -s -o /dev/null -w 'senza: %{size_download} byte\n' https://corso-api-json.giuseppebosi.com/api/v1/books?limit=100curl -s -o /dev/null -w 'gzip: %{size_download} byte (%{http_version}, encoding: %header{content-encoding})\n' \--compressed https://corso-api-json.giuseppebosi.com/api/v1/books?limit=100- -w '… %{size_download} …'
- variabili di write-out:
size_download= byte ricevuti,http_version= versione HTTP negoziata,%header{nome}= valore di un header della risposta - --compressed
- aggiunge
Accept-Encodingcon tutti gli algoritmi che curl supporta e decomprime la risposta automaticamente. Equivale a-H 'Accept-Encoding: gzip'più la decompressione
La seconda riga mostra encoding: gzip (o zstd sul server pubblico, dove risponde Caddy) e un size_download diverse volte più piccolo: la compressione c’è anche in locale, perché la fa l’API.
Rate limit: provocare un 429 con giudizio
Sezione intitolata “Rate limit: provocare un 429 con giudizio”Non serve martellare il server per vederlo. Un ciclo di poco più di 30 richieste basta, una sola volta:
for i in $(seq 1 40); docurl -s -o /dev/null -w '%{http_code}\n' https://corso-api-json.giuseppebosi.com/api/v1/healthdone | sort | uniq -c- $(seq 1 40)
- genera i numeri da 1 a 40: il ciclo gira 40 volte
- -w '%{http_code}\n'
- stampa solo lo status code di ogni richiesta
- | sort | uniq -c
- ordina gli status e conta quante volte compare ciascuno
30 200 10 429Guardiamo una risposta 429 per intero (con un’istanza locale del server configurata con limite 5/minute, per non disturbare quello pubblico):
HTTP/1.1 429 Too Many Requestscontent-type: application/jsonretry-after: 10
{"error":{"code":"rate_limited","message":"Troppe richieste: limite 5 per 1 minute. Riprova tra poco."}}Retry-After: 10 è l’istruzione per il client: aspetta 10 secondi. Il body ha il solito formato error. Dopo il ciclo, aspetta un minuto prima di continuare gli esercizi.
Python e TypeScript
Sezione intitolata “Python e TypeScript”Un client che riusa la connessione, conserva gli ETag per URL e rispetta Retry-After:
# pip install httpx → python3 cache.pyimport time
import httpx
BASE = "https://corso-api-json.giuseppebosi.com/api/v1"cache: dict[str, tuple[str, dict]] = {} # url -> (etag, json)
# un solo Client = una sola connessione riusata (keep-alive) e header comuniclient = httpx.Client(base_url=BASE, timeout=10, headers={"Accept-Encoding": "gzip, zstd"})
def get(path: str) -> dict: headers = {} if path in cache: headers["If-None-Match"] = cache[path][0] # "ho già questa versione" while True: r = client.get(path, headers=headers) if r.status_code == 429: attesa = int(r.headers.get("Retry-After", "5")) print(f"429: aspetto {attesa}s") time.sleep(attesa) continue break if r.status_code == 304: print(f"{path}: 304, uso la cache") return cache[path][1] r.raise_for_status() if etag := r.headers.get("ETag"): cache[path] = (etag, r.json()) print(f"{path}: {r.status_code}, {len(r.content)} byte, encoding={r.headers.get('Content-Encoding', '-')}, " f"cache-control={r.headers.get('Cache-Control')}") return r.json()
t0 = time.perf_counter()libro = get("/books/7")libro = get("/books/7") # seconda volta: 304print(libro["title"], f"({(time.perf_counter() - t0) * 1000:.0f} ms per due richieste sulla stessa connessione)")// node --experimental-strip-types cache.tsconst BASE = "https://corso-api-json.giuseppebosi.com/api/v1";const cache = new Map<string, { etag: string; body: unknown }>(); // url -> versione conosciutaconst dormi = (s: number) => new Promise((r) => setTimeout(r, s * 1000));
// fetch di Node riusa le connessioni (keep-alive) per la stessa origine: nessun setup extraasync function get(path: string): Promise<any> { const headers: Record<string, string> = { "Accept-Encoding": "gzip, zstd" }; const noto = cache.get(path); if (noto) headers["If-None-Match"] = noto.etag; // "ho già questa versione" for (;;) { const r = await fetch(BASE + path, { headers }); if (r.status === 429) { const attesa = Number(r.headers.get("Retry-After") ?? 5); console.log(`429: aspetto ${attesa}s`); await dormi(attesa); continue; } if (r.status === 304) { console.log(`${path}: 304, uso la cache`); return noto!.body; } if (!r.ok) throw new Error(`HTTP ${r.status}`); const body = await r.json(); const etag = r.headers.get("ETag"); if (etag) cache.set(path, { etag, body }); console.log(`${path}: ${r.status}, encoding=${r.headers.get("content-encoding") ?? "-"}, cache-control=${r.headers.get("cache-control")}`); return body; }}
const t0 = performance.now();let libro = await get("/books/7");libro = await get("/books/7"); // seconda volta: 304console.log(libro.title, `(${(performance.now() - t0).toFixed(0)} ms per due richieste)`);Output atteso (in produzione):
/books/7: 200, 375 byte, encoding=zstd, cache-control=public, max-age=60/books/7: 304, uso la cacheOltre Trieste (… ms per due richieste sulla stessa connessione)Prova subito
Sezione intitolata “Prova subito”Esegui due volte di seguito e guarda etag e cache-control negli header della risposta (il browser gestisce If-None-Match da solo: la seconda volta è servita dalla sua cache).
Header della risposta
Header della risposta
Esercizio
Sezione intitolata “Esercizio”Provalo online, senza installare nulla:
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/.
- Scarica
/books/7con ETag, poi (con la sandbox) modifica il prezzo del libro 7 e riscarica con il token: che status ottieni, e perché l’ETag è diverso? - Misura con
-w '%{time_total}\n'dieci richieste in un ciclofor(ogni curl apre una connessione nuova) e confrontale con lo script Python/TS che ne riusa una. Quanto costa l’handshake? - Cosa succede se ignori
Retry-Aftere continui a chiamare durante un 429? Rispondi ragionando, senza provarlo sul server pubblico.
Soluzione
200con un nuovoetag: l’impronta è calcolata sul JSON della risposta, e il prezzo è cambiato. Inoltre con il tokencache-controldiventano-store.- Tipicamente 40-120 ms per richiesta con connessione nuova (TCP + TLS) contro 5-20 ms per le successive sulla stessa connessione: il costo fisso domina sulle API veloci.
- Le richieste continuano a ricevere 429 e a contare nella finestra: resti bloccato più a lungo. Alcuni server aumentano la penalità ai recidivi.
Errori comuni
Sezione intitolata “Errori comuni”- Un
httpx.get/fetch“nudo” per ogni chiamata in un ciclo: niente keep-alive, niente cache degli ETag, niente header comuni. - Mettere in cache risposte
no-store(con token): dati privati che finiscono in una cache condivisa. - Ritentare subito su 429 (o su 5xx): peggiora il problema. Serve attesa, meglio se crescente.
- Dare per scontata la compressione: qui la applica l’API stessa, ma molte API la delegano al reverse proxy e in sviluppo, senza proxy, non c’è. Controlla
content-encoding.
In sintesi
Sezione intitolata “In sintesi”ETag/304 evitano di riscaricare, Cache-Control dice chi può conservare cosa, la compressione riduce i byte, il keep-alive elimina gli handshake, e 429 + Retry-After regolano il traffico. Nel prossimo capitolo vedrai le difese dell’API dall’altro lato: iniezioni, validazione, CORS e segreti.