Postman e curl, esercizi spiegati
Cinque richieste, un pezzo alla volta
- 20 minuti di lettura
Cinque richieste, dalla più semplice. Ognuna ha lo stesso ritmo:
- Prevedi: leggi il comando e scrivi su un foglio cosa risponde il server. Prima di aprire la risposta.
- In italiano: cosa chiede il comando, a parole.
- Passo per passo: i pezzi del comando, uno per uno.
- Cosa portiamo a casa: la cosa da ricordare.
Per provarle servono il server acceso (fastapi dev api/deposito.py, nella cartella dello zip della palestra) e un secondo terminale. Se non hai ancora letto la teoria, leggila prima: qui non si rispiega cos'è ogni opzione.
A · Dov'è il M12?
Lucia Ferri, la capotreno, chiede dove sta il M12. Poi chiede del M99, che non esiste.
curl http://127.0.0.1:8000/treni/M12
curl -i http://127.0.0.1:8000/treni/M99Prevedi Scrivi su un foglio cosa ti aspetti, poi apri.
{"tipo":"metro","vagoni":4,"stato":"in servizio","stazione":"Porta Codice","codice":"M12"}HTTP/1.1 404 Not Found
date: Thu, 19 Nov 2026 17:24:59 GMT
server: uvicorn
content-length: 43
content-type: application/json
{"detail":"Nessun treno con il codice M99"}- Il primo comando non ha
-i: solo il corpo, il treno. - Il secondo ha
-i: prima la riga del codice (404 Not Found), poi gli header, poi una riga vuota, poi il corpo. - La data cambia a ogni richiesta: è quella del tuo server.
In italiano. Chiedo la scheda del treno M12, poi quella del M99, e nel secondo caso voglio vedere anche il codice.
Passo per passo.
| Pezzo | Cosa fa |
|---|---|
curl | Il programma: fa una richiesta e stampa la risposta |
-i | Stampa anche la riga del codice e gli header |
http://127.0.0.1:8000/treni/M99 | L'indirizzo: il computer stesso (127.0.0.1), la porta 8000, il percorso /treni/M99 |
(nessun -X) | Senza -X il verbo è GET |
Cosa portiamo a casa. Senza -i, un 404 e una risposta riuscita si assomigliano: il corpo da solo non dice se è andata bene. Per capire, serve il codice.
B · I tram, in colonna
Ernesto Pozzi vuole solo i tram, e leggibili.
curl -s "http://127.0.0.1:8000/treni?tipo=tram" | python3 -m json.toolPrevedi Scrivi su un foglio cosa ti aspetti, poi apri.
[
{
"tipo": "tram",
"vagoni": 2,
"stato": "in servizio",
"stazione": "Ponte Ciclo",
"codice": "T05"
},
{
"tipo": "tram",
"vagoni": 3,
"stato": "in servizio",
"stazione": "Via Variabile",
"codice": "T28"
}
]- La centrale filtra per
tipo=tram: solo T05 e T28. json.toolrimette il JSON in colonna, una chiave per riga.
In italiano. Chiedo i treni di tipo tram, senza barra di avanzamento, e passo la risposta a uno strumento che la mette in colonna.
Passo per passo.
| Pezzo | Cosa fa |
|---|---|
"…/treni?tipo=tram" | Il ? apre la query: tipo è il filtro, tram il valore. Le virgolette doppie proteggono il ? |
-s | Niente barra di avanzamento: senza, finirebbe in mezzo alla risposta |
| la barra verticale | Si chiama pipe: passa quello che stampa curl al comando dopo |
python3 -m json.tool | Legge il JSON e lo stampa a capo, con i rientri |
E se il filtro ha uno spazio? Il valore in deposito ne ha uno:
curl -i "http://127.0.0.1:8000/treni?stato=in deposito"
curl -i "http://127.0.0.1:8000/treni?stato=in%20deposito"Prevedi Scrivi su un foglio cosa ti aspetti, poi apri.
curl: (3) URL rejected: Malformed input to a URL functionHTTP/1.1 200 OK
date: Thu, 19 Nov 2026 17:24:59 GMT
server: uvicorn
content-length: 163
content-type: application/json
[{"tipo":"metro","vagoni":6,"stato":"in deposito","stazione":null,"codice":"M10"},{"tipo":"metro","vagoni":4,"stato":"in deposito","stazione":null,"codice":"M20"}]- Con lo spazio, curl non manda nemmeno la richiesta: l'indirizzo non è valido.
- Con
%20al posto dello spazio, la richiesta parte: due treni, M10 e M20.
Cosa portiamo a casa. L'indirizzo tra virgolette doppie, e mai uno spazio dentro: %20. Se curl dice URL rejected, guarda l'indirizzo.
C · Un treno nuovo
Il deposito riceve il M22, una metro da 4 vagoni. Prima proviamo senza l'header, poi come si deve.
curl -i -X POST http://127.0.0.1:8000/treni -d '{"codice": "M22", "tipo": "metro", "vagoni": 4}'Prevedi Scrivi su un foglio cosa ti aspetti, poi apri.
HTTP/1.1 422 Unprocessable Entity
date: Thu, 19 Nov 2026 17:25:06 GMT
server: uvicorn
content-length: 204
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":"{\"codice\": \"M22\", \"tipo\": \"metro\", \"vagoni\": 4}"}]}422: la centrale ha ricevuto un corpo ma non l'ha letto come JSON. Dice «Input should be a valid dictionary or object»: si aspettava un oggetto, ha trovato un testo.- Il corpo è giusto. Manca l'header che dice «è JSON».
Ora con l'header, sul comando spezzato su più righe:
curl -i -X POST http://127.0.0.1:8000/treni \
-H "Content-Type: application/json" \
-d '{"codice": "M22", "tipo": "metro", "vagoni": 4}'Prevedi Scrivi su un foglio cosa ti aspetti, poi apri.
HTTP/1.1 201 Created
date: Thu, 19 Nov 2026 17:24:59 GMT
server: uvicorn
content-length: 80
content-type: application/json
{"tipo":"metro","vagoni":4,"stato":"in deposito","stazione":null,"codice":"M22"}201 Created: il treno è stato creato.- Nel corpo, il treno com'è adesso: lo stato e la stazione, che non hai mandato, hanno i valori di partenza (
in deposito, nessuna stazione). - Se rilanci lo stesso comando:
409 Conflict,{"detail":"Il treno M22 c'è già"}. La centrale se lo ricorda.
In italiano. Mando una richiesta POST a /treni, dico che il corpo è JSON, e nel corpo scrivo il treno nuovo.
Passo per passo.
| Pezzo | Cosa fa |
|---|---|
-X POST | Il verbo: «crea» |
-H "Content-Type: application/json" | L'header: «quello che segue è JSON» |
-d '…' | Il corpo. Tra virgolette semplici, così quelle doppie del JSON passano intatte |
\ in fondo alla riga | «Il comando continua alla riga dopo». Dopo la barra non va scritto niente, nemmeno uno spazio |
Cosa portiamo a casa. -d senza -H dà 422: il corpo è giusto, ma la centrale non sa che è JSON.
D · Un treno in meno
Ivo toglie dalla centrale il M22, appena aggiunto per sbaglio. Lo togliamo due volte.
curl -i -X DELETE http://127.0.0.1:8000/treni/M22
curl -i -X DELETE http://127.0.0.1:8000/treni/M22Prevedi Scrivi su un foglio cosa ti aspetti, poi apri.
HTTP/1.1 204 No Content
date: Thu, 19 Nov 2026 17:24:59 GMT
server: uvicorn
HTTP/1.1 404 Not Found
date: Thu, 19 Nov 2026 17:24:59 GMT
server: uvicorn
content-length: 43
content-type: application/json
{"detail":"Nessun treno con il codice M22"}- La prima volta
204 No Content: è andata bene, e non c'è niente da dire. Per questo il corpo non c'è e non c'è nemmeno la rigacontent-type. - La seconda volta il treno non c'è più:
404.
In italiano. Dico alla centrale «cancella il M22», e lo dico due volte per vedere cosa succede la seconda.
Passo per passo.
| Pezzo | Cosa fa |
|---|---|
-X DELETE | Il verbo: «togli» |
/treni/M22 | Il treno è nell'indirizzo, niente corpo e niente -H |
-i | Senza, un 204 non stamperebbe niente: sembrerebbe che il comando non abbia fatto nulla |
Cosa portiamo a casa. Una risposta muta non è una risposta rotta: con -i il 204 si vede. E senza -X DELETE, curl farebbe una GET, che sul M22 darebbe solo la scheda del treno.
E · Il biglietto
Marta Villa, la capostazione, fa il login, poi chiede alla centrale chi è.
curl -i http://127.0.0.1:8000/me
curl -s -X POST http://127.0.0.1:8000/login \
-H "Content-Type: application/json" \
-d '{"badge": "B-07", "password": "menta-marta"}'Prevedi Scrivi su un foglio cosa ti aspetti, poi apri.
HTTP/1.1 401 Unauthorized
date: Thu, 19 Nov 2026 17:24:59 GMT
server: uvicorn
www-authenticate: Bearer
content-length: 99
content-type: application/json
{"detail":"Serve il biglietto: fai il login, poi manda l'header Authorization: Bearer <biglietto>"}{"access_token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJCLTA3IiwiZXhwIjoxNzk1MTEyNjk5fQ.msS6JmKN4l5ze6LBfal-ejOqmT9LyUoIEGg-VXyE-90","token_type":"bearer"}- Senza biglietto:
401, e l'headerwww-authenticate: Bearerdice quale tipo di biglietto serve. - Il login risponde con l'
access_token: la stringa lunga che comincia coneyJ. Il tuo sarà diverso: cambia a ogni login e a ogni accensione del server.
Copia il valore di access_token (senza le virgolette) e mettilo in una variabile della shell. Poi usalo nell'header Authorization, nella forma Bearer + spazio + biglietto:
BIGLIETTO="incolla-qui-il-biglietto"
curl -s http://127.0.0.1:8000/me -H "Authorization: Bearer $BIGLIETTO"
curl -i http://127.0.0.1:8000/me -H "Authorization: $BIGLIETTO"Prevedi Scrivi su un foglio cosa ti aspetti, poi apri.
{"badge":"B-07","nome":"Marta Villa","ruolo":"capostazione"}HTTP/1.1 401 Unauthorized
date: Thu, 19 Nov 2026 17:25:06 GMT
server: uvicorn
www-authenticate: Bearer
content-length: 99
content-type: application/json
{"detail":"Serve il biglietto: fai il login, poi manda l'header Authorization: Bearer <biglietto>"}- La prima: il biglietto arriva giusto, e la centrale risponde con chi sei.
- La seconda: ho dimenticato la parola
Bearer. Il biglietto c'è, ma non nella forma che la centrale riconosce:401lo stesso.
In italiano. Faccio il login e ricevo un biglietto. Poi, in ogni richiesta che lo richiede, scrivo nell'header Authorization la parola Bearer e il biglietto.
Il disegno.
Cosa portiamo a casa. L'header è Authorization: Bearer e il biglietto, separati da uno spazio. Un 401 dopo il login vuol dire quasi sempre: manca Bearer, il biglietto è scaduto, o il server è stato riavviato (la chiave è nuova: rifai il login).
F · Gli stessi, in Postman
Postman non ha un output da copiare: si fa, e si guarda. Ripercorri A, C ed E con questa checklist (la teoria spiega ogni passo). Prima, una volta sola: crea la collezione «Deposito Linea Menta» e nella scheda Variables mettici baseUrl = http://127.0.0.1:8000.
| Cosa fai | Cosa vedi |
|---|---|
Nuova richiesta GET, indirizzo {{baseUrl}}/treni/M12, Send | Sotto: 200 OK e il JSON del M12 (nella scheda Body) |
Cambia in {{baseUrl}}/treni/M99, Send | 404 Not Found e il messaggio «Nessun treno con il codice M99» |
Nuova richiesta POST, {{baseUrl}}/treni, Body → raw → Text → il JSON del M22, Send | 422: è lo stesso errore di curl senza -H |
| Cambia il menu da Text a JSON, Send | 201 Created |
POST {{baseUrl}}/login, Body raw JSON con badge e password, nella scheda Scripts → Post-response la riga che salva biglietto, Send | 200, e nella scheda Variables della collezione biglietto ha un valore |
GET {{baseUrl}}/me, Authorization → Bearer Token → {{biglietto}}, Send | 200 e i dati di Marta Villa. Tolto il Token: 401 |
| Spegni il server (Ctrl+C), Send | Could not send request: il server è spento, la richiesta non arriva da nessuna parte |
Salva ogni richiesta con un nome chiaro (Cmd+S o Ctrl+S): «GET un treno · M12», «POST nuovo treno · M22».