Il viaggio di una richiesta
Cosa parte dal telefono, cosa torna indietro
- 12 minuti di lettura
Sono le 5:40 a Porta Codice. Rosa Bellini apre sul telefono l'app InfoMenta e tocca «Prossime partenze». Un attimo dopo legge: M12 alle 05:42.
In quell'attimo è successo tutto quello che c'è in questo capitolo. Dal telefono è partita una richiesta. È arrivata a un programma che gira su un altro computer. Il programma ha cercato le partenze e ha mandato indietro una risposta.
Chi chiede si chiama client: il telefono di Rosa, il browser, il terminale. Chi risponde si chiama server. Si parlano con HTTP: un insieme di regole su come si scrive una domanda e come si scrive una risposta. Sono regole di testo, e le puoi leggere anche tu.
Il disegno
Client L'API Il database
(l'app di Rosa, il browser, (InfoMenta, in FastAPI) (PostgreSQL, più avanti)
curl nel terminale)
│ │ │
│ GET /partenze?stazione_id=1 │ │
│ ───────────────────────────▶ │ cerca le partenze │
│ │ │
│ ◀─────────────────────────── │ │
│ 200 e le partenze in JSON │ │Tre regole, sempre:
- Il client chiede, il server risponde. Mai il contrario: InfoMenta non scrive a Rosa di sua iniziativa.
- Una richiesta, una risposta. Per sapere un'altra cosa, il client fa un'altra richiesta.
- Il client non tocca mai il database. Passa sempre dal server, che decide cosa si può vedere e cosa si può cambiare. In questo libro i dati di InfoMenta stanno ancora in un dizionario Python; il database vero arriva in Perché un database.
Un server che risponde ai programmi (l'app, curl, Python) invece che alle persone si chiama API. InfoMenta è un'API: risponde con dati, non con pagine da guardare (tranne una, il tabellone, che trovi più sotto).
Accendi InfoMenta
Per vedere un viaggio dal vivo serve un server acceso. Nello zip del capitolo ce n'è uno già pronto: InfoMenta, l'API della Linea Menta. Non la scrivi tu (il tuo primo server arriva in Il primo server): la accendi e le fai domande. Lo zip si scarica dalla palestra.
Nel primo terminale (nella cartella dello zip, venv acceso):
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-viaggio-di-una-richiesta']
INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
INFO: Started reloader process [78676] using WatchFiles
INFO: Started server process [78686]
INFO: Waiting for application startup.
INFO: Application startup complete.Il server è acceso e aspetta. Il terminale resta occupato finché non premi Ctrl+C: lascialo così.
Nel secondo terminale (stessa cartella), fai la domanda di Rosa con curl, un client che sta nel terminale:
curl -i "http://127.0.0.1:8000/partenze?stazione_id=1"Con -i curl stampa la risposta intera; con -v anche la richiesta che parte. Le altre opzioni sono nel capitolo Fare richieste: per ora copia i comandi così come sono, virgolette comprese.
La richiesta
Ecco cosa parte dal client, preso da curl -v:
GET /partenze?stazione_id=1 HTTP/1.1
Host: 127.0.0.1:8000
User-Agent: curl/8.7.1
Accept: */*
Quattro pezzi, sempre in quest'ordine:
- La riga di richiesta: tre parole separate da uno spazio. Il verbo
GETdice cosa vuoi fare («dammi»). Il percorso/partenzedice quale cosa vuoi, e dopo il?è attaccata la querystazione_id=1, i dettagli della domanda.HTTP/1.1è la versione delle regole: non la scegli tu. - Gli header: informazioni in più, una per riga, nella forma
Nome: valore. Qui sono tre: a quale computer va la richiesta, chi la fa, cosa accetta indietro. - Una riga vuota: vuol dire «gli header sono finiti».
- Il corpo: i dati che il client manda. In una GET è vuoto: chiedi, non mandi niente.
GET legge. Quando invece il client manda qualcosa di nuovo, il verbo è POST, e il corpo non è più vuoto (lo vedi più sotto). Gli altri verbi sono nel capitolo Verbi e codici.
La risposta
Ecco cosa torna, preso da curl -i:
HTTP/1.1 200 OK
date: Thu, 19 Nov 2026 15:55:19 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"}]Gli stessi quattro pezzi:
- La riga di stato: la versione, il codice e la sua frase.
200 OKvuol dire «tutto bene, ecco quello che hai chiesto». Il numero è per i programmi, la frase è per le persone. Gli altri codici sono nel capitolo Verbi e codici. - Gli header: quando ha risposto (
date), chi ha risposto (server: uvicorn è il programma che fa girare InfoMenta), quanti byte è lungo il corpo (content-length), di che tipo è il corpo (content-type). - La riga vuota.
- Il corpo: la risposta vera, in JSON. Qui una lista di tre partenze, e la prima è l'M12 delle 05:42.
Lo stesso viaggio, visto dal server
Marta Villa, la capostazione di Piazza Query, guarda dall'altra parte del filo: il terminale del server. A ogni richiesta che arriva, il server scrive una riga. Nel terminale del server compare:
INFO: 127.0.0.1:62787 - "GET /partenze?stazione_id=1 HTTP/1.1" 200 OKChi ha chiesto (127.0.0.1, cioè questo computer, seguito da un numero di porta che il client sceglie a caso a ogni richiesta), la riga di richiesta tra virgolette, il codice e la frase della risposta. È lo stesso viaggio, raccontato in una riga. Se una richiesta qui non compare, al server non è mai arrivata.
Un indirizzo, pezzo per pezzo
L'indirizzo che hai dato a curl (o che scrivi nel browser) contiene tutto quello che serve per trovare il server e scrivere la riga di richiesta.
http://127.0.0.1:8000/partenze?stazione_id=1
└──┬──┘└───┬───┘└─┬─┘└───┬───┘└──────┬─────┘
│ │ │ │ query
│ │ │ percorso
│ │ porta
│ host
protocollo| Pezzo | Qui | Cosa dice |
|---|---|---|
| Protocollo | http:// | Le regole con cui si parla: HTTP. Con https:// sono le stesse regole, ma cifrate: chi sta in mezzo non legge |
| Host | 127.0.0.1 | Quale computer. 127.0.0.1 (o localhost) vuol dire sempre «questo computer». Su internet al suo posto c'è un nome, quello del sito |
| Porta | :8000 | Quale programma, su quel computer. InfoMenta ascolta sulla porta 8000. Se la porta manca, http usa la 80 e https la 443 |
| Percorso | /partenze | Quale cosa vuoi, dentro il server. Comincia sempre con / |
| Query | ?stazione_id=1 | I dettagli della domanda: dopo il ?, coppie nome=valore |
Con più dettagli, le coppie si separano con &. I tram fermi a Ponte Ciclo:
/treni?tipo=tram&stazione_id=4Due coppie: tipo vale tram, stazione_id vale 4. L'ordine delle coppie non conta.
Nella riga di richiesta finiscono percorso e query; host e porta vanno nell'header Host. Il protocollo è la lingua stessa della conversazione: la riga di richiesta lo ripete in fondo, con la sua versione (HTTP/1.1).
Un indirizzo non può contenere spazi. Uno spazio si scrive %20: «Porta Codice» diventa Porta%20Codice, e il server lo rimette a posto da solo. Il browser lo fa per te mentre scrivi. curl no: con uno spazio nell'indirizzo si ferma con un errore (è nella pagina Se qualcosa va storto).
Il corpo: JSON, e non solo
Quasi sempre un'API risponde in JSON, il formato di testo che hai visto in Moduli e file. Somiglia ai dizionari e alle liste di Python, con poche differenze: solo virgolette doppie, true e false invece di True e False, null invece di None. La tabella completa è lì.
Il corpo però arriva come testo. Per lavorarci in Python lo trasformi con json.loads, e diventa un dizionario o una lista (lo fai negli esercizi spiegati).
Non tutti i corpi sono JSON. Il tabellone di Porta Codice, http://127.0.0.1:8000/, è una pagina web:
curl -i http://127.0.0.1:8000/HTTP/1.1 200 OK
date: Thu, 19 Nov 2026 15:55:19 GMT
server: uvicorn
content-length: 610
content-type: text/html; charset=utf-8
<!doctype html>
<html lang="it">
<head><meta charset="utf-8"><title>Linea Menta · Porta Codice</title></head>
…Chi dice di che tipo è il corpo è l'header Content-Type: application/json per il JSON, text/html per una pagina web (charset=utf-8 dice come sono scritte le lettere, accentate comprese). Il browser lo legge per decidere cosa fare: il JSON te lo mostra come testo, l'HTML lo disegna come pagina.
Una richiesta con il corpo
Ernesto Pozzi, il capo deposito, aggiunge alla linea un treno nuovo, l'M18. Questa volta il client non chiede: manda. Il verbo è POST, e i dati del treno viaggiano nel corpo:
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}Due header nuovi, perché adesso c'è un corpo: Content-Type dice al server che il corpo è JSON, Content-Length quanto è lungo. La risposta la smonti negli esercizi spiegati.
Quattro header da conoscere
| Header | Va in | Dice | Per esempio |
|---|---|---|---|
Content-Type | richiesta e risposta | Di che tipo è il corpo | application/json, text/html |
Accept | richiesta | Che tipo vorrei ricevere | */* (qualsiasi), application/json |
Authorization | richiesta | Chi sono: il badge, la chiave d'accesso | Bearer … |
User-Agent | richiesta | Quale programma fa la richiesta | curl/8.7.1 |
Authorization per ora lo nomini soltanto: il login vero è nel libro Login e sicurezza. E il tuo User-Agent può avere un altro numero: su Ubuntu curl ha una versione diversa da quella del Mac.
Dove guardo?
Il bigino del capitolo: una domanda, un posto dove guardare.
| Voglio sapere | Guardo | Nella domanda di Rosa |
|---|---|---|
| Cosa vuole fare il client | il verbo, nella riga di richiesta | GET |
| Quale cosa chiede | il percorso | /partenze |
| Con quali dettagli | la query, dopo il ? | stazione_id=1 |
| A quale computer e programma | host e porta, nell'header Host | 127.0.0.1:8000 |
| Se è andata bene | il codice, nella riga di stato | 200 |
| Di che tipo è la risposta | l'header content-type | application/json |
| La risposta vera | il corpo, dopo la riga vuota | la lista delle partenze |
Verbo e codice sono le due parole più importanti del viaggio: il primo dice cosa vuole il client, il secondo com'è andata. Il prossimo capitolo, Verbi e codici, li guarda tutti, uno per uno.
Ricorda
- Il client chiede, il server risponde. Il client non tocca mai il database.
- Richiesta: riga di richiesta (verbo, percorso con la query, versione), header, riga vuota, corpo.
- Risposta: riga di stato (versione, codice, frase), header, riga vuota, corpo.
- Indirizzo: protocollo, host, porta, percorso, query (
?la apre,=lega nome e valore,&separa le coppie). - Il corpo è quasi sempre JSON, e
Content-Typedice di che tipo è.