Vai al contenuto
code-to-code

Apro l'indice…

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

HTTP e API3. Fare richiestep. 56

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):

Terminale
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 JSON

Per 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 OK

1 · 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/:

  1. Apri gli strumenti per sviluppatori: F12 su Windows, Cmd+Opt+I su Mac.
  2. Scegli la scheda Rete (in inglese Network).
  3. Ricarica la pagina: la scheda registra solo quello che succede mentre è aperta.
  4. Clicca il filtro Fetch/XHR: restano solo le chiamate all'API, quelle che la pagina fa per prendere i dati.
  5. 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:

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:

OpzioneCosa faEsempio
-iMostra anche la riga di stato e gli header della rispostacurl -i "…"
-sSilenzioso: niente barra di avanzamentocurl -s "…"
-vMostra tutto, anche la richiesta che partecurl -v "…"
-XSceglie il verbo. Senza, è GET-X DELETE
-HAggiunge un header alla richiesta-H "Authorization: Bearer B-12"
-dManda un corpo (e da solo fa già una POST)-d '{"testo": "Ciao"}'
-LSegue i rimandi: un 301 lo porta al nuovo indirizzocurl -L "…"

Con -i vedi la risposta intera, come nel capitolo Il viaggio di una richiesta:

Terminale
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:

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"
    }
]

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:

Terminale
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=1

curl si ferma lì. Con -L segue il rimando, e stampa le partenze:

Terminale
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.

Terminale
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:

HTTP
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:

  1. New → HTTP: si apre una richiesta vuota.
  2. Nel menu a tendina a sinistra dell'indirizzo, da GET passa a POST.
  3. L'indirizzo: http://127.0.0.1:8000/annunci.
  4. Scheda Body → raw → nel menu a destra, JSON. Scrivi il corpo: {"testo": "Il M12 parte dal binario 2"}.
  5. 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.

Python
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'}
M12
  • params= è la query, scritta come dizionario: httpx aggiunge da solo ?, = e & all'indirizzo (lo vedi in risposta.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.

partenze = [ {"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"}, ]partenzelist012dict"ora""05:42""treno""M12""stazione_id"1"direzione""Piazza Query"dict"ora""05:54""treno""M14""stazione_id"1"direzione""Piazza Query"dict"ora""06:06""treno""M12""stazione_id"1"direzione""Piazza Query"
Dopo risposta.json()

Gli altri pezzi della richiesta sono altri argomenti, sempre dizionari:

Per mandareScriviCome curl
La queryparams={"stazione_id": 1}?stazione_id=1 nell'indirizzo
Un corpo JSONjson={"testo": "Ciao"}-H "Content-Type: application/json" -d '…'
Un headerheaders={"Authorization": "Bearer B-12"}-H "Authorization: Bearer B-12"
Un altro verbohttpx.post, httpx.put, httpx.delete-X POST, -X PUT, -X DELETE

E per leggere la risposta:

VuoiScriviEsempio
Il codicerisposta.status_code201
Il corpo, in Pythonrisposta.json()una lista, un dizionario
Un header della rispostarisposta.headers["location"]"/partenze"

Con json= httpx scrive il corpo in JSON e mette l'header Content-Type da solo:

Python
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:

Python
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:

Python
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 S01

Il 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:

Python
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 pezzoIl browsercurlPostmanhttpx
Il verbosolo GET, dalla barra-X POSTil menu a tendinahttpx.post(…)
La querynell'indirizzo, dopo ?nell'indirizzo, tra virgolettenell'indirizzo, o Paramsparams={…}
Un header—-H "Nome: valore"Headersheaders={…}
Un corpo JSON—-H "Content-Type: application/json" -d '…'Body → raw → JSONjson={…}
Il codicescheda Rete, Headers-i, la prima rigasopra la risposta.status_code
Il corpo della rispostascheda Rete, Responsequello che stampaBody.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 -d sempre -H "Content-Type: application/json".
  • httpx: params= per la query, json= per il corpo, headers= per gli header. Poi .status_code e .json().
  • Prima il codice, poi il JSON: in un 404 il corpo ha solo detail.