Vai al contenuto
code-to-code

Apro l'indice…

↑ ↓ per scegliere, Invio per aprire, Esc per chiudere

HTTP e API3. Fare richiestep. 63

Fare richieste, esercizi spiegati

Cinque richieste, quattro strumenti

  • 20 minuti di lettura

Cinque esempi, uno strumento alla volta, e alla fine uno sui test. Ognuno ha lo stesso ritmo:

  1. Prevedi: leggi la richiesta e scrivi su un foglio cosa risponderà InfoMenta. Prima di aprire la risposta.
  2. In italiano: cosa succede, a parole.
  3. Passo per passo: la richiesta e la risposta, un pezzo alla volta.
  4. Cosa portiamo a casa: la cosa da ricordare.

Per provarli ti serve InfoMenta accesa. Nel primo terminale (venv acceso, nella cartella dello zip):

Terminale
fastapi dev palestra/infomenta.py

I comandi curl e Python vanno nel secondo terminale, con il venv acceso anche lì. Ogni volta che riavvii InfoMenta, i suoi dati tornano come all'inizio: se un esempio ti dà un numero diverso dal mio, riavviala (Ctrl+C, poi di nuovo fastapi dev) e riprova.


A · Il tabellone di Marta

Marta Villa, capostazione di Piazza Query, apre nel browser il tabellone di Porta Codice: http://127.0.0.1:8000/. Vede una tabella con tre partenze. Ma da dove arrivano i dati?

La pagina che il browser riceve è questa (la stampa curl, con curl -s http://127.0.0.1:8000/):

<!doctype html>
<html lang="it">
<head><meta charset="utf-8"><title>Linea Menta · Porta Codice</title></head>
<body>
<h1>Porta Codice · prossime partenze</h1>
<table id="partenze"><tr><th>Ora</th><th>Treno</th><th>Direzione</th></tr></table>
<script>
fetch("/partenze?stazione_id=1")
  .then((risposta) => risposta.json())
  .then((partenze) => {
    const tabella = document.getElementById("partenze");
    for (const p of partenze) {
      tabella.insertAdjacentHTML("beforeend", "<tr><td>" + p.ora + "</td><td>" + p.treno + "</td><td>" + p.direzione + "</td></tr>");
    }
  });
</script>
</body>
</html>

Marta apre gli strumenti per sviluppatori (F12 su Windows, Cmd+Opt+I su Mac), sceglie la scheda Rete, ricarica la pagina e clicca il filtro Fetch/XHR.

Prevedi Scrivi su un foglio cosa ti aspetti, poi apri.

Resta una richiesta sola: partenze?stazione_id=1. Cliccandola, in Headers c'è il verbo GET e il codice 200; in Response c'è il JSON delle tre partenze, lo stesso che stampa curl:

Terminale
curl -s "http://127.0.0.1:8000/partenze?stazione_id=1" | python3 -m json.tool
[
    {
        "ora": "05:42",
        "treno": "M12",
        "stazione_id": 1,
        "direzione": "Piazza Query"
    },
    {
        "ora": "05:54",
        "treno": "M14",
        "stazione_id": 1,
        "direzione": "Piazza Query"
    },
    {
        "ora": "06:06",
        "treno": "M12",
        "stazione_id": 1,
        "direzione": "Piazza Query"
    }
]

In italiano. Il JavaScript non lo sai ancora leggere, e non serve: basta una riga, fetch("/partenze?stazione_id=1"). È una richiesta, come quelle che fai tu con curl.

  1. Il browser chiede la pagina: GET /. Arriva l'HTML, con la tabella vuota.
  2. Dentro la pagina c'è uno script, che chiede i dati: GET /partenze?stazione_id=1. Arriva il JSON.
  3. Lo script mette ogni partenza in una riga della tabella.

Passo per passo, le richieste che vede la scheda Rete:

#Chi la faLa richiestaIl codiceCosa arrivaResta con Fetch/XHR?
1il browser, per la barra dell'indirizzoGET /200la pagina, in HTMLno: è un documento
2lo script dentro la paginaGET /partenze?stazione_id=1200le partenze, in JSONsì: è una chiamata all'API

Cosa portiamo a casa. Una pagina web è un client come gli altri. Con la scheda Rete e il filtro Fetch/XHR vedi quali API usa, con quali richieste: è il modo più veloce per scoprire da dove arrivano i dati di una pagina.


B · L'annuncio di Ivo

Ivo Brambati, il manutentore, al deposito ha solo un terminale. Vuole mandare un annuncio all'altoparlante e scrive:

Terminale
curl -i -X POST http://127.0.0.1:8000/annunci -d '{"testo": "Treno in arrivo al binario 1"}'

Il verbo è giusto, il percorso è giusto, il JSON è giusto. Che codice risponde InfoMenta?

Prevedi Scrivi su un foglio cosa ti aspetti, poi apri.
HTTP/1.1 422 Unprocessable Entity
date: Thu, 19 Nov 2026 16:00:42 GMT
server: uvicorn
content-length: 192
content-type: application/json

{"detail":[{"type":"model_attributes_type","loc":["body"],"msg":"Input should be a valid dictionary or object to extract fields from","input":"{\"testo\": \"Treno in arrivo al binario 1\"}"}]}

422: i dati non vanno bene. Il messaggio dice «mi aspettavo un oggetto JSON», e input mostra cosa è arrivato: il JSON di Ivo, ma come testo, tra virgolette.

In italiano. Manca l'header Content-Type. Senza, curl dice a InfoMenta che il corpo è un modulo, come quello di una pagina web con i campi da riempire. FastAPI non lo legge come JSON: per lui è una stringa qualsiasi, e lo stampo vuole un oggetto con il campo testo.

Passo per passo, le richieste viste con -v. Senza -H, curl mette da solo questo header:

HTTP
POST /annunci HTTP/1.1
Host: 127.0.0.1:8000
User-Agent: curl/8.7.1
Accept: */*
Content-Length: 41
Content-Type: application/x-www-form-urlencoded

{"testo": "Treno in arrivo al binario 1"}

application/x-www-form-urlencoded è il nome tecnico del «modulo». Con -H "Content-Type: application/json" l'header diventa quello giusto:

Terminale
curl -i -X POST http://127.0.0.1:8000/annunci \
  -H "Content-Type: application/json" \
  -d '{"testo": "Treno in arrivo al binario 1"}'
HTTP/1.1 201 Created
date: Thu, 19 Nov 2026 16:00:42 GMT
server: uvicorn
content-length: 47
content-type: application/json

{"testo":"Treno in arrivo al binario 1","id":1}

Cosa portiamo a casa. Con -d, sempre anche -H "Content-Type: application/json". Postman (con raw → JSON) e httpx (con json=) questo header lo mettono da soli.


C · Il treno nuovo di Nadia

Nadia Russo, la guardia giurata, preferisce i bottoni. In Postman prepara la richiesta per un tram nuovo a Ponte Ciclo:

  1. Il menu a tendina: POST. L'indirizzo: http://127.0.0.1:8000/treni.
  2. Body → raw → JSON, e il corpo:
JSON
{"codice": "T28", "tipo": "tram", "vagoni": 2, "stazione_id": 4}
  1. Send. Poi, senza cambiare niente, Send un'altra volta.

Cosa risponde InfoMenta la prima volta? E la seconda?

Prevedi Scrivi su un foglio cosa ti aspetti, poi apri.

La prima volta 201 Created, con il treno nuovo e il suo id. La seconda 409 Conflict: il codice T28 c'è già.

Le risposte che vede Nadia sono queste. Te le mostro con la stessa richiesta fatta da curl, perché Postman non si può copiare in una pagina; ma il codice e il corpo sono identici.

Terminale
curl -i -X POST http://127.0.0.1:8000/treni \
  -H "Content-Type: application/json" \
  -d '{"codice": "T28", "tipo": "tram", "vagoni": 2, "stazione_id": 4}'
HTTP/1.1 201 Created
date: Thu, 19 Nov 2026 16:00:42 GMT
server: uvicorn
content-length: 78
content-type: application/json

{"codice":"T28","tipo":"tram","vagoni":2,"stazione_id":4,"guasto":null,"id":7}

Lo stesso comando, la seconda volta:

HTTP/1.1 409 Conflict
date: Thu, 19 Nov 2026 16:00:42 GMT
server: uvicorn
content-length: 48
content-type: application/json

{"detail":"Codice già usato da un altro treno"}

In italiano. Una POST chiede «crea». Due POST sono due richieste di creare. La prima va bene: InfoMenta sceglie l'id (7, il più grande più uno) e risponde 201. La seconda chiede di creare un altro T28, e InfoMenta non vuole due treni con lo stesso codice: 409.

Il disegno.

inizio POST /treni se il codice è già di un treno sì: errore 409 Codice già usato da un altro treno passo id = il più grande + 1 restituisci 201 e il treno con l'idPOST /treniil codice è già diun treno409 Codice già usato da unaltro trenoid = il più grande + 1restituisci 201 e il trenocon l'idnosì
La POST che crea un treno

Passo per passo:

SendIl codiceIl corpo della rispostaI treni in InfoMenta, dopo
1201il T28, con "id": 7 e "guasto": nullsette: i sei di partenza e il T28
2409{"detail": "Codice già usato da un altro treno"}sempre sette: non è cambiato niente

Il campo guasto Nadia non l'ha mandato: è facoltativo, e InfoMenta lo riempie con null, il None del JSON.

Cosa portiamo a casa. Una GET si può ripetere quanto vuoi: legge e basta. Una POST no: ogni Send crea, o prova a creare. In Postman la richiesta resta lì pronta, e premere Send due volte è facilissimo.


D · Il viaggio di Lucia

Lucia Ferri, capotreno, vuole sul tablet il tempo di viaggio tra due stazioni. InfoMenta lo sa: GET /viaggio?da=…&a=…. Lucia prova da Python, con una richiesta giusta e una sbagliata apposta. Il codice va in un file nuovo, palestra/prova_viaggio.py, e si lancia con python3 palestra/prova_viaggio.py.

Python
import httpx

risposta = httpx.get("http://127.0.0.1:8000/viaggio", params={"da": 1, "a": 5})
print(risposta.status_code)
viaggio = risposta.json()
print(viaggio["minuti"], "minuti,", viaggio["prezzo"], "euro")

risposta = httpx.get("http://127.0.0.1:8000/viaggio", params={"da": 3, "a": 3})
print(risposta.status_code)
print(risposta.json())
Prevedi Scrivi su un foglio cosa ti aspetti, poi apri.
200
12 minuti, 2.2 euro
400
{'detail': 'Partenza e arrivo sono la stessa stazione'}

Da Porta Codice (1) a Piazza Query (5) ci sono quattro fermate, tre minuti l'una. Da Largo Lista a Largo Lista, invece, non si va da nessuna parte: 400, la richiesta non ha senso.

In italiano.

  1. Chiedo il viaggio da 1 a 5. httpx costruisce l'indirizzo con la query.
  2. Il codice è 200: il corpo è un dizionario, e ne leggo due chiavi.
  3. Chiedo il viaggio da 3 a 3. Il codice è 400: il corpo ha solo detail.

Passo per passo. Nel terminale del server compaiono le due richieste, con la query che ha scritto httpx:

INFO:     127.0.0.1:59905 - "GET /viaggio?da=1&a=5 HTTP/1.1" 200 OK
INFO:     127.0.0.1:59906 - "GET /viaggio?da=3&a=3 HTTP/1.1" 400 Bad Request
La rigaCosa faCosa vale
params={"da": 1, "a": 5}la query, scritta come dizionario?da=1&a=5 nell'indirizzo
risposta.status_codeil codice200
risposta.json()il corpo, da JSON a Pythonun dizionario con da, a, fermate, minuti, prezzo
viaggio["minuti"]una chiave del dizionario12

E se Lucia, dopo il 400, leggesse lo stesso minuti? In un altro file, palestra/prova_viaggio_sbagliato.py:

Python
import httpx

risposta = httpx.get("http://127.0.0.1:8000/viaggio", params={"da": 3, "a": 3})
viaggio = risposta.json()
print(viaggio["minuti"], "minuti")
Traceback (most recent call last):
  File "~/corso/http-fare-richieste/palestra/prova_viaggio_sbagliato.py", line 5, in <module>
    print(viaggio["minuti"], "minuti")
          ~~~~~~~^^^^^^^^^^
KeyError: 'minuti'

Il corpo di un 400 è {"detail": …}: la chiave minuti non c'è. È lo stesso KeyError del capitolo I dizionari.

Il disegno.

viaggio = {"detail": "Partenza e arrivo sono la stessa stazione"}viaggiodict"detail""Partenza e arrivo sono la stessa stazione"
Il corpo del 400

Cosa portiamo a casa. Prima il codice, poi il JSON. httpx non si ferma per un 400 o un 404: ti consegna la risposta, e tocca a te guardare status_code prima di leggere le chiavi.


E · La stessa funzione, due client

Lucia mette la richiesta in una funzione, che riceve il client da fuori. Poi la prova due volte: con un httpx.Client che parla con InfoMenta accesa, e con un TestClient, quello dei test. Il file sta in palestra/, accanto a infomenta.py: per esempio palestra/prova_client.py.

Python
import httpx
from fastapi.testclient import TestClient

import infomenta


def minuti_di_viaggio(client, da, a):
    risposta = client.get("/viaggio", params={"da": da, "a": a})
    return risposta.json()["minuti"]


with httpx.Client(base_url="http://127.0.0.1:8000") as client:
    print("con il server:", minuti_di_viaggio(client, 1, 5))

finto = TestClient(infomenta.app)
print("con il TestClient:", minuti_di_viaggio(finto, 1, 5))

Cosa stampa? E quante righe nuove compaiono nel terminale del server?

Prevedi Scrivi su un foglio cosa ti aspetti, poi apri.
con il server: 12
con il TestClient: 12

Nel terminale del server, una riga sola:

INFO:     127.0.0.1:59908 - "GET /viaggio?da=1&a=5 HTTP/1.1" 200 OK

Il TestClient non è passato dal server: ha chiamato InfoMenta direttamente, dentro lo stesso programma Python. Per questo i test funzionano anche con InfoMenta spenta.

In italiano. La funzione non sa con chi sta parlando, e non le serve saperlo: chiama client.get, e qualcuno risponde. Con l'httpx.Client la richiesta viaggia fino al server acceso; con il TestClient arriva a InfoMenta senza uscire da Python.

C'è una differenza sola, e conviene saperla. Lucia prova il vecchio indirizzo degli orari, che risponde con un rimando (301). Un altro file, palestra/prova_rimandi.py:

Python
import httpx
from fastapi.testclient import TestClient

import infomenta

with httpx.Client(base_url="http://127.0.0.1:8000") as client:
    print("httpx:", client.get("/orari").status_code)

finto = TestClient(infomenta.app)
print("TestClient:", finto.get("/orari").status_code)
print("TestClient, senza seguire:", finto.get("/orari", follow_redirects=False).status_code)
Prevedi Scrivi su un foglio cosa ti aspetti, poi apri.
httpx: 301
TestClient: 200
TestClient, senza seguire: 301

httpx, se non gli dici niente, non segue i rimandi: ti dà il 301. Il TestClient invece li segue da solo, e arriva al 200 di /partenze. Con follow_redirects=False si comportano allo stesso modo.

Passo per passo:

Il clientget("/orari")Con follow_redirects=FalseCon follow_redirects=True
httpx.Client301301200
TestClient200301200

Cosa portiamo a casa. Una funzione che riceve il client si prova senza server, ed è per questo che negli esercizi del capitolo è sempre il primo argomento. E quando il risultato dipende da un comportamento «di default», non fidarti: scrivilo tu. Ti servirà nell'esercizio 5.


Pronto? La palestra ti aspetta: sei funzioni che fanno richieste a InfoMenta, con i test.