Fare richieste
La stessa domanda, quattro strumenti
- 12 minuti di lettura
Nei primi due capitoli le richieste le hai lette: al massimo hai copiato un comando curl già scritto. In questo le scrivi tu.
Gli strumenti sono quattro: il browser, curl, Postman e Python. Sembrano diversissimi, ma fanno tutti la stessa cosa: preparano una richiesta (verbo, percorso, header, corpo), la mandano e ti mostrano la risposta (codice, header, corpo). Cambia solo dove scrivi i pezzi.
Prima: accendi InfoMenta
Le domande le facciamo a InfoMenta, l'API della Linea Menta che trovi nello zip del capitolo. Nel primo terminale (venv acceso):
cd ~/corso/http-fare-richieste
source .venv/bin/activate
fastapi dev palestra/infomenta.py ⚡️ Starting FastAPI in development mode
🐍 Using import string: infomenta:app
🌐 Server started at http://127.0.0.1:8000
Documentation at http://127.0.0.1:8000/docs
Logs:
INFO: Will watch for changes in these directories: ['~/corso/http-fare-richieste']
INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
INFO: Started reloader process [33132] using WatchFiles
INFO: Started server process [33142]
INFO: Waiting for application startup.
INFO: Application startup complete.Il server occupa il terminale: lascialo lì. Per curl e Python apri un secondo terminale, con cd ~/corso/http-fare-richieste e source .venv/bin/activate anche lì. Su Windows, tutti e due sono terminali di Ubuntu.
Il disegno
Quattro persone della Linea Menta fanno la stessa domanda, «quali treni partono da Porta Codice?», ognuna con il suo strumento.
CHI CHIEDE LA RICHIESTA CHI RISPONDE
il browser (Marta Villa) ──┐
curl (Ivo Brambati) ──┤ GET /partenze?stazione_id=1
Postman (Nadia Russo) ──┼──────────────────────────────────▶ InfoMenta
Python, httpx (Lucia Ferri) ──┘ 127.0.0.1:8000
◀──────────────────────────────────
200 e le partenze in JSONPer InfoMenta sono tutte uguali: arriva una richiesta, parte una risposta. Nel terminale del server compare una riga per ogni richiesta, chiunque l'abbia mandata:
INFO: 127.0.0.1:59877 - "GET /partenze?stazione_id=1 HTTP/1.1" 200 OK1 · Il browser
La barra dell'indirizzo. Scrivi http://127.0.0.1:8000/partenze?stazione_id=1 e premi Invio: il browser manda una GET e ti mostra il corpo della risposta, il JSON delle partenze.
La barra fa solo GET. Non puoi scriverci «fai una POST» o «aggiungi questo header»: per tutto il resto servono gli altri strumenti.
La scheda Rete. Una pagina web, mentre la guardi, fa le sue richieste da sola. Gli strumenti per sviluppatori del browser te le mostrano tutte. Prova con il tabellone di InfoMenta, http://127.0.0.1:8000/:
- Apri gli strumenti per sviluppatori:
F12su Windows,Cmd+Opt+Isu Mac. - Scegli la scheda Rete (in inglese Network).
- Ricarica la pagina: la scheda registra solo quello che succede mentre è aperta.
- Clicca il filtro Fetch/XHR: restano solo le chiamate all'API, quelle che la pagina fa per prendere i dati.
- Clicca la richiesta
partenze?stazione_id=1. In Headers trovi l'indirizzo, il verbo e il codice; in Response il JSON.
Il tabellone arriva come una pagina HTML con la tabella vuota, e un pezzetto di JavaScript che chiede le partenze a InfoMenta e la riempie. Per questo le richieste sono due: la pagina, poi i dati.
2 · curl
curl fa una richiesta dal terminale e stampa la risposta. Nel secondo terminale:
curl "http://127.0.0.1:8000/partenze?stazione_id=1"[{"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"}]Da solo, curl stampa solo il corpo. Le opzioni aggiungono il resto:
| Opzione | Cosa fa | Esempio |
|---|---|---|
-i | Mostra anche la riga di stato e gli header della risposta | curl -i "…" |
-s | Silenzioso: niente barra di avanzamento | curl -s "…" |
-v | Mostra tutto, anche la richiesta che parte | curl -v "…" |
-X | Sceglie il verbo. Senza, è GET | -X DELETE |
-H | Aggiunge un header alla richiesta | -H "Authorization: Bearer B-12" |
-d | Manda un corpo (e da solo fa già una POST) | -d '{"testo": "Ciao"}' |
-L | Segue i rimandi: un 301 lo porta al nuovo indirizzo | curl -L "…" |
Con -i vedi la risposta intera, come nel capitolo Il viaggio di una richiesta:
curl -i "http://127.0.0.1:8000/partenze?stazione_id=1"HTTP/1.1 200 OK
date: Thu, 19 Nov 2026 16:00:15 GMT
server: uvicorn
content-length: 220
content-type: application/json
[{"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"}]Il JSON su una riga sola si legge male. Passalo a python3 -m json.tool, che lo mette in colonna. La barra verticale | dà l'uscita di curl in pasto al comando dopo; -s toglie la barra di avanzamento, che in mezzo darebbe fastidio:
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"
}
]Un rimando. /orari è il vecchio indirizzo delle partenze. Con -i vedi che InfoMenta non risponde con i dati, ma con un 301 e l'header location, il nuovo indirizzo:
curl -i "http://127.0.0.1:8000/orari?stazione_id=1"HTTP/1.1 301 Moved Permanently
date: Thu, 19 Nov 2026 16:00:15 GMT
server: uvicorn
content-length: 0
location: /partenze?stazione_id=1curl si ferma lì. Con -L segue il rimando, e stampa le partenze:
curl -L "http://127.0.0.1:8000/orari?stazione_id=1"[{"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"}]Mandare dati. Un annuncio nuovo all'altoparlante è una POST su /annunci, con un corpo JSON. Il comando è lungo: la \ a fine riga dice al terminale che continua sotto.
curl -i -X POST http://127.0.0.1:8000/annunci \
-H "Content-Type: application/json" \
-d '{"testo": "Il M12 parte dal binario 2"}'HTTP/1.1 201 Created
date: Thu, 19 Nov 2026 16:00:15 GMT
server: uvicorn
content-length: 45
content-type: application/json
{"testo":"Il M12 parte dal binario 2","id":1}Cosa è partito davvero? Con -v curl te lo mostra: le righe che cominciano con > sono la richiesta, quelle con < la risposta. Ecco la richiesta, senza i segni:
POST /annunci HTTP/1.1
Host: 127.0.0.1:8000
User-Agent: curl/8.7.1
Accept: */*
Content-Type: application/json
Content-Length: 39
{"testo": "Il M12 parte dal binario 2"}L'header Content-Type: application/json è quello che hai scritto con -H: dice a InfoMenta «il corpo è JSON». Senza, curl manda il corpo come se fosse un modulo, e InfoMenta risponde 422. Lo vedi negli esercizi spiegati.
3 · Postman
Postman fa le stesse richieste di curl, con i bottoni al posto delle opzioni. Si usa l'app desktop: su Windows quella di Windows, non dentro Ubuntu (raggiunge lo stesso InfoMenta su 127.0.0.1:8000). La versione nel browser no: con un server sul tuo computer risponde Could not send request.
La stessa POST dell'annuncio:
- New → HTTP: si apre una richiesta vuota.
- Nel menu a tendina a sinistra dell'indirizzo, da GET passa a POST.
- L'indirizzo:
http://127.0.0.1:8000/annunci. - Scheda Body → raw → nel menu a destra, JSON. Scrivi il corpo:
{"testo": "Il M12 parte dal binario 2"}. - Send.
Sotto compare la risposta: il codice (201 Created), il corpo in Body e gli header in Headers. È la stessa che hai visto con curl. Quando scegli JSON, l'header Content-Type: application/json Postman lo aggiunge da solo: è un errore in meno.
La query si scrive nell'indirizzo, oppure nella scheda Params (Postman la aggiunge all'indirizzo per te); un header nella scheda Headers. Le collezioni, le variabili e il resto stanno in Postman e curl.
4 · Python, con httpx
httpx è una libreria che fa richieste HTTP da Python. È già nel requirements.txt dello zip: la usano anche i test.
Per provare gli esempi, scrivili in un file nuovo nella cartella palestra/, per esempio palestra/prova.py, e lancialo dal secondo terminale con python3 palestra/prova.py. InfoMenta deve essere accesa. Ogni esempio è un programma a sé, con il suo import httpx in cima: scrivilo al posto del precedente.
import httpx
risposta = httpx.get("http://127.0.0.1:8000/partenze", params={"stazione_id": 1})
print(risposta.status_code)
print(risposta.url)
print(risposta.headers["content-type"])
partenze = risposta.json()
print(partenze[0])
print(partenze[0]["treno"])Prevedi Scrivi su un foglio cosa ti aspetti, poi apri.
200
http://127.0.0.1:8000/partenze?stazione_id=1
application/json
{'ora': '05:42', 'treno': 'M12', 'stazione_id': 1, 'direzione': 'Piazza Query'}
M12params=è la query, scritta come dizionario: httpx aggiunge da solo?,=e&all'indirizzo (lo vedi inrisposta.url)..json()trasforma il corpo da JSON a Python: una lista di dizionari, che sai già leggere. Il JSON in Python l'hai visto in Moduli e file.
Il disegno.
Gli altri pezzi della richiesta sono altri argomenti, sempre dizionari:
| Per mandare | Scrivi | Come curl |
|---|---|---|
| La query | params={"stazione_id": 1} | ?stazione_id=1 nell'indirizzo |
| Un corpo JSON | json={"testo": "Ciao"} | -H "Content-Type: application/json" -d '…' |
| Un header | headers={"Authorization": "Bearer B-12"} | -H "Authorization: Bearer B-12" |
| Un altro verbo | httpx.post, httpx.put, httpx.delete | -X POST, -X PUT, -X DELETE |
E per leggere la risposta:
| Vuoi | Scrivi | Esempio |
|---|---|---|
| Il codice | risposta.status_code | 201 |
| Il corpo, in Python | risposta.json() | una lista, un dizionario |
| Un header della risposta | risposta.headers["location"] | "/partenze" |
Con json= httpx scrive il corpo in JSON e mette l'header Content-Type da solo:
import httpx
risposta = httpx.post("http://127.0.0.1:8000/annunci", json={"testo": "Il M12 parte dal binario 2"})
print(risposta.status_code)
print(risposta.json())201
{'testo': 'Il M12 parte dal binario 2', 'id': 3}L'id è 3: InfoMenta conta gli annunci da quando è accesa, e due li hai già mandati con curl (con -i e con -v). Se il tuo numero è diverso, hai mandato più o meno annunci: va bene così. E se ne mandi più di tre nello stesso minuto, il quarto riceve un 429: l'altoparlante si riposa.
Un header si manda con headers=. Sergio Colombo prova a leggere il registro del deposito con il suo badge:
import httpx
risposta = httpx.get("http://127.0.0.1:8000/deposito/registro", headers={"Authorization": "Bearer B-04"})
print(risposta.status_code)
print(risposta.json())403
{'detail': 'Sergio Colombo, il registro del deposito è solo per il capo deposito'}Attenzione: un 403 non è un errore di Python. httpx ti consegna la risposta, qualunque codice abbia. Prima guardi il codice, poi leggi il JSON: in un 403 o in un 404 il corpo ha solo detail.
Il client. Quando le richieste sono tante, l'inizio dell'indirizzo lo scrivi una volta sola. httpx.Client(base_url=…) è un client che lo ricorda, e i percorsi diventano corti:
import httpx
with httpx.Client(base_url="http://127.0.0.1:8000") as client:
stazione = client.get("/stazioni/6").json()
treni = client.get("/treni", params={"stazione_id": 6}).json()
print(stazione["nome"], stazione["aperta"])
print(len(treni), treni[0]["codice"])Vecchia Fiera False
1 S01Il with funziona come con open: alla fine del blocco il client chiude la connessione da solo.
Perché le funzioni ricevono il client. Negli esercizi del capitolo ogni funzione riceve il client da fuori, invece di crearselo:
def orari_di(client: httpx.Client, stazione_id: int) -> list[str]:
risposta = client.get("/partenze", params={"stazione_id": stazione_id})
...Così chi la chiama decide con chi parla. Quando lanci il file, le passi un httpx.Client che parla con InfoMenta accesa. Quando la provano i test, le passano un TestClient: si usa allo stesso modo (get, post, params=, .json()), ma parla con InfoMenta direttamente, senza server. Per questo i test non hanno bisogno di InfoMenta accesa.
La stessa richiesta, quattro volte
Il bigino del capitolo: dove si scrive ogni pezzo, in ogni strumento.
| Il pezzo | Il browser | curl | Postman | httpx |
|---|---|---|---|---|
| Il verbo | solo GET, dalla barra | -X POST | il menu a tendina | httpx.post(…) |
| La query | nell'indirizzo, dopo ? | nell'indirizzo, tra virgolette | nell'indirizzo, o Params | params={…} |
| Un header | — | -H "Nome: valore" | Headers | headers={…} |
| Un corpo JSON | — | -H "Content-Type: application/json" -d '…' | Body → raw → JSON | json={…} |
| Il codice | scheda Rete, Headers | -i, la prima riga | sopra la risposta | .status_code |
| Il corpo della risposta | scheda Rete, Response | quello che stampa | Body | .json() |
E dopo
Finora InfoMenta l'ha scritta qualcun altro, e tu le hai fatto domande. Nel prossimo capitolo, Il primo server, scrivi la tua API. E la provi con questi stessi quattro strumenti: sono il tuo banco di prova per tutto il resto del libro.
Ricorda
- La stessa richiesta si fa in quattro modi. Il server non sa, e non gli importa, chi l'ha scritta.
- La barra del browser fa solo GET. La scheda Rete (filtro Fetch/XHR) mostra le richieste che una pagina fa da sola.
- curl: indirizzo tra virgolette doppie, JSON tra apici singoli, con
-dsempre-H "Content-Type: application/json". - httpx:
params=per la query,json=per il corpo,headers=per gli header. Poi.status_codee.json(). - Prima il codice, poi il JSON: in un 404 il corpo ha solo
detail.