Vai al contenuto
code-to-code

Apro l'indice…

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

HTTP e API1. Il viaggio di una richiestap. 7

Il viaggio di una richiesta, esercizi spiegati

Cinque viaggi, smontati un pezzo alla volta

  • 20 minuti di lettura

Cinque viaggi veri, fatti a InfoMenta. Ognuno ha lo stesso ritmo:

  1. Prevedi: leggi la richiesta o la risposta e scrivi su un foglio le risposte alle domande. Prima di aprire la soluzione.
  2. In italiano: cosa dice il client, cosa dice il server, a parole.
  3. Passo per passo: una riga alla volta, cosa vuol dire.
  4. Cosa portiamo a casa: la cosa da ricordare.

Ogni esempio lo puoi rifare tu: InfoMenta accesa nel primo terminale (fastapi dev palestra/infomenta.py), il comando nel secondo. Se non sai come si accende, è nella teoria.


A · La domanda di Sergio

Sergio Colombo, il macchinista, porta il treno di servizio fino a Vecchia Fiera, la stazione 6, chiusa al pubblico da vent'anni. Chiede a InfoMenta come è segnata. Con -v curl stampa tutto il viaggio, e con -H Sergio aggiunge un header suo (le opzioni di curl sono nel capitolo Fare richieste).

Terminale
curl -v -H "Accept: application/json" http://127.0.0.1:8000/stazioni/6
*   Trying 127.0.0.1:8000...
* Connected to 127.0.0.1 (127.0.0.1) port 8000
> GET /stazioni/6 HTTP/1.1
> Host: 127.0.0.1:8000
> User-Agent: curl/8.7.1
> Accept: application/json
> 
* Request completely sent off
< HTTP/1.1 200 OK
< date: Thu, 19 Nov 2026 16:04:16 GMT
< server: uvicorn
< content-length: 46
< content-type: application/json
< 
* Connection #0 to host 127.0.0.1 left intact
{"id":6,"nome":"Vecchia Fiera","aperta":false}

Prevedi:

  1. Quali righe sono la richiesta? Quali la risposta? E le altre?
  2. Il verbo e il percorso.
  3. Quante righe di header ha la richiesta? Quale ha aggiunto Sergio?
  4. Cosa c'è nel corpo della richiesta?
Prevedi Scrivi su un foglio cosa ti aspetti, poi apri.
  1. Le righe con > davanti sono la richiesta, quelle con < la risposta. Le righe con * sono curl che racconta cosa fa: si collega, ha finito di mandare, chiude. L'ultima riga, senza segno, è il corpo della risposta.
  2. Il verbo è GET, il percorso /stazioni/6. Niente ?, quindi niente query.
  3. Tre: Host, User-Agent, Accept. Sergio ha scritto Accept: application/json: senza -H, curl avrebbe mandato Accept: */*, «va bene tutto».
  4. Niente. La riga > da sola è la riga vuota che chiude gli header, e dopo non c'è altro: in una GET il corpo è vuoto.

In italiano. Sergio dice: «Dammi la stazione 6. Vado al computer 127.0.0.1, porta 8000. Sono curl. Mi va bene il JSON.»

Passo per passo. La richiesta, senza i segni di curl:

RigaÈDice
GET /stazioni/6 HTTP/1.1riga di richiestaverbo, percorso, versione
Host: 127.0.0.1:8000headera quale computer e porta va
User-Agent: curl/8.7.1headerquale programma chiede
Accept: application/jsonheadercosa vorrebbe ricevere
(vuota)fine degli headerdopo, il corpo: qui vuoto

Cosa portiamo a casa. curl -v è una finestra sul filo: > va dal client al server, < torna indietro. Per smontare una richiesta, togli i segni e leggi una riga alla volta.


B · La risposta su Vecchia Fiera

Sempre lo stesso viaggio, adesso dal lato che torna. Le righe con <, senza il segno, più il corpo:

HTTP
HTTP/1.1 200 OK
date: Thu, 19 Nov 2026 16:04:16 GMT
server: uvicorn
content-length: 46
content-type: application/json

{"id":6,"nome":"Vecchia Fiera","aperta":false}

Prevedi:

  1. Il codice, e la sua frase.
  2. Di che tipo è il corpo?
  3. Quanti byte è lungo il corpo?
  4. Vecchia Fiera è aperta?
Prevedi Scrivi su un foglio cosa ti aspetti, poi apri.
  1. 200, e la frase è OK: tutto bene.
  2. JSON: lo dice content-type: application/json.
  3. 46: lo dice content-length. Conta pure i caratteri del corpo: sono proprio 46.
  4. No: "aperta":false. In JSON false si scrive minuscolo.

In italiano. InfoMenta risponde: «Tutto bene. Ti mando 46 byte di JSON. Eccoli: la stazione 6 si chiama Vecchia Fiera ed è chiusa.»

Passo per passo.

RigaÈDice
HTTP/1.1 200 OKriga di statoversione, codice, frase
date: …headerquando ha risposto
server: uvicornheaderquale programma ha risposto
content-length: 46headerquanti byte è lungo il corpo
content-type: application/jsonheaderdi che tipo è il corpo
(vuota)fine degli headerdopo, il corpo
{"id":6, …}corpola risposta vera

Cosa portiamo a casa. 200 vuol dire che la domanda è andata bene, non che la notizia è buona. La stazione è chiusa, ma la risposta è giusta: il server ha trovato quello che Sergio chiedeva.


C · Un indirizzo con due dettagli

Tommaso Greco, macchinista anche lui, è a Ponte Ciclo (la stazione 4) e vuole sapere quali tram ci sono fermi.

Terminale
curl -i "http://127.0.0.1:8000/treni?tipo=tram&stazione_id=4"

Prevedi, guardando solo l'indirizzo:

  1. Protocollo, host, porta.
  2. Il percorso.
  3. Quante coppie ci sono nella query? Per ognuna, il nome e il valore.
Prevedi Scrivi su un foglio cosa ti aspetti, poi apri.
  1. http, 127.0.0.1, 8000.
  2. /treni: dalla prima / dopo la porta fino al ?, escluso.
  3. Due coppie, separate da &: tipo vale tram, stazione_id vale 4.

In italiano. Tommaso dice: «Dammi i treni. Ma solo i tram, e solo quelli della stazione 4.» Il percorso dice quale cosa vuole, i treni; ogni coppia della query aggiunge un dettaglio.

Il disegno.

http://127.0.0.1:8000/treni?tipo=tram&stazione_id=4
└──┬──┘└───┬───┘└─┬─┘└──┬─┘└───────────┬──────────┘
   │       │      │     │              query
   │       │      │     percorso
   │       │      porta
   │       host
   protocollo

Passo per passo, la query:

PezzoCos'è
?qui comincia la query
tipo=tramla prima coppia: nome tipo, valore tram
&separa una coppia dalla successiva
stazione_id=4la seconda coppia: nome stazione_id, valore 4

La risposta:

HTTP/1.1 200 OK
date: Thu, 19 Nov 2026 16:02:35 GMT
server: uvicorn
content-length: 92
content-type: application/json

[{"codice":"T09","tipo":"tram","vagoni":1,"stazione_id":4,"guasto":"porte bloccate","id":5}]

Un tram solo, il T09, con le porte bloccate. E nel terminale del server compare:

INFO:     127.0.0.1:62792 - "GET /treni?tipo=tram&stazione_id=4 HTTP/1.1" 200 OK

Nel suo registro il server scrive percorso e query, non host e porta: quelli sono serviti ad arrivare fin lì.

E se Tommaso scrive di fretta e lascia uno spazio dopo la &?

Terminale
curl -i "http://127.0.0.1:8000/treni?tipo=tram& stazione_id=4"
curl: (3) URL rejected: Malformed input to a URL function

curl non parte nemmeno: un indirizzo non può contenere spazi. Nel registro del server non compare niente, perché la richiesta non è mai partita.

Cosa portiamo a casa. Il ? apre la query, = lega il nome al valore, & separa le coppie. E l'indirizzo va tra virgolette: dentro ci sono ? e &, che il terminale altrimenti prova a leggere a modo suo.


D · Il treno nuovo di Ernesto

Ernesto Pozzi, il capo deposito, mette in linea un treno nuovo, l'M18, a Porta Codice. Questa volta il client manda dei dati. Il comando è lungo: il \ a fine riga vuol dire «continua sotto».

Terminale
curl -v http://127.0.0.1:8000/treni \
    -H "Content-Type: application/json" \
    -d '{"codice": "M18", "tipo": "metro", "vagoni": 4, "stazione_id": 1}'

La richiesta che parte:

HTTP
POST /treni HTTP/1.1
Host: 127.0.0.1:8000
User-Agent: curl/8.7.1
Accept: */*
Content-Type: application/json
Content-Length: 65

{"codice": "M18", "tipo": "metro", "vagoni": 4, "stazione_id": 1}

La risposta che torna:

HTTP
HTTP/1.1 201 Created
date: Thu, 19 Nov 2026 15:55:35 GMT
server: uvicorn
content-length: 79
content-type: application/json

{"codice":"M18","tipo":"metro","vagoni":4,"stazione_id":1,"guasto":null,"id":7}

Prevedi:

  1. Il verbo. Perché non è GET?
  2. Quale header della richiesta dice a InfoMenta che il corpo è JSON?
  3. Nel corpo della risposta ci sono due campi che Ernesto non ha mandato. Quali? Chi li ha scritti?
Prevedi Scrivi su un foglio cosa ti aspetti, poi apri.
  1. POST: Ernesto non chiede una cosa che c'è già, ne manda una nuova. Con -d curl usa POST da solo.
  2. Content-Type: application/json. Il suo vicino, Content-Length: 65, dice quanto è lungo il corpo.
  3. guasto e id, e li ha scritti InfoMenta. guasto vale null: Ernesto non ne ha mandato uno, quindi «nessun guasto». L'id è 7: InfoMenta aveva sei treni, e al nuovo ha dato il numero dopo.

In italiano. Ernesto dice: «Ecco un treno nuovo, in JSON: mettilo nella linea.» InfoMenta risponde: «Fatto. Si chiama 7, ed ecco com'è adesso.»

Il disegno.

inizio curl POST /treni passo parte il corpo JSON, con Content-Type passo InfoMenta sceglie l'id: 7 passo il campo guasto vale null restituisci 201 Created e il treno con l'idcurl POST /treniparte il corpo JSON, conContent-TypeInfoMenta sceglie l'id: 7il campo guasto vale nullrestituisci 201 Created e iltreno con l'id
Il viaggio della POST

Passo per passo.

RichiestaRisposta
Prima rigaPOST /treni HTTP/1.1HTTP/1.1 201 Created
Il tipo del corpoContent-Type: application/jsoncontent-type: application/json
La lunghezza del corpoContent-Length: 65content-length: 79
Il corpoil treno senza idil treno con l'id

201 Created vuol dire «creato»: è il «tutto bene» di una POST. I codici sono il prossimo capitolo, Verbi e codici.

Cosa portiamo a casa. In una POST il corpo viaggia anche all'andata, e allora la richiesta ha Content-Type e Content-Length come la risposta. L'id non lo sceglie il client: lo sceglie il server, e lo leggi nella risposta.


E · Dal JSON a Python

Il corpo arriva come testo. Per lavorarci, Sergio lo trasforma con json.loads, come in Moduli e file. Ecco la risposta su Vecchia Fiera dell'esempio A, in Python:

Python
import json

corpo = '{"id":6,"nome":"Vecchia Fiera","aperta":false}'
stazione = json.loads(corpo)

print(corpo)
print(stazione)
print(type(stazione))
print(stazione["aperta"])

Prevedi le quattro righe.

Prevedi Scrivi su un foglio cosa ti aspetti, poi apri.
{"id":6,"nome":"Vecchia Fiera","aperta":false}
{'id': 6, 'nome': 'Vecchia Fiera', 'aperta': False}
<class 'dict'>
False
  • Riga 1: corpo è una stringa, e si stampa così com'è: virgolette doppie, false minuscolo.
  • Riga 2: stazione è un dizionario Python. Python lo stampa con le virgolette singole e False maiuscolo.
  • Riga 3: lo conferma type(): un oggetto JSON tra graffe diventa un dict.
  • Riga 4: il false del JSON è diventato False, un bool vero e proprio.

Il disegno.

stazione = {"id": 6, "nome": "Vecchia Fiera", "aperta": False}stazionedict"id"6"nome""Vecchia Fiera""aperta"False
Dopo json.loads

E il treno di Ernesto dell'esempio D:

Python
import json

corpo = '{"codice":"M18","tipo":"metro","vagoni":4,"stazione_id":1,"guasto":null,"id":7}'
treno = json.loads(corpo)

print(treno["guasto"])
print(type(treno["vagoni"]))
print(treno["codice"] + " ha " + str(treno["vagoni"]) + " vagoni")
Prevedi Scrivi su un foglio cosa ti aspetti, poi apri.
None
<class 'int'>
M18 ha 4 vagoni

Il null del JSON diventa None; il 4 resta un numero, un int. Per attaccarlo a un testo serve str(), come sempre.

treno = {"codice": "M18", "tipo": "metro", "vagoni": 4, "stazione_id": 1, "guasto": None, "id": 7}trenodict"codice""M18""tipo""metro""vagoni"4"stazione_id"1"guasto"None"id"7
Il treno dopo json.loads

In italiano. Dal server arriva una riga di testo, con le sue virgolette doppie e le sue parole del JSON. json.loads la legge e costruisce il dizionario Python che quel testo descrive, traducendo le parole: false diventa False, null diventa None.

Passo per passo, da JSON a Python:

Nel corpo (JSON)Dopo json.loads (Python)type() dice
{"id": 6, …}{'id': 6, …}dict
[ … ][ … ]list
"Vecchia Fiera"'Vecchia Fiera'str
44int
falseFalsebool
nullNoneNoneType

Cosa portiamo a casa. Sul filo viaggia testo. json.loads lo trasforma in dizionari e liste, e da lì in poi lavori con le quadre come in I dizionari.


Pronto? Nella palestra ti aspettano sei viaggi da smontare, ognuno con il suo test.