Postman e curl
Mandare richieste a un server, e salvarle
- 10 minuti di lettura
Un server FastAPI risponde a chi gli scrive. Chi gli scrive si chiama client: il browser è un client, e anche curl e Postman lo sono.
Il browser sa fare bene una cosa sola: una richiesta GET, scrivendo un indirizzo. Per una POST con un corpo JSON, un header, un biglietto di login, ti serve un client che ti lasci scrivere ogni pezzo della richiesta. Ne usiamo due: curl, nel terminale, e Postman, con i bottoni.
Cos'è una richiesta (verbo, indirizzo, header, corpo) e cosa sono i codici lo trovi in Il viaggio di una richiesta e in Verbi e codici. Qui impari a usare gli attrezzi.
TU IL SERVER (fastapi dev)
curl ... ── richiesta ───▶ GET /treni/M12
Postman ◀── risposta ──── 200 + header + corpo JSONIl server, in questo capitolo, è sempre lo stesso: l'API del deposito della Linea Menta, che trovi nello zip della palestra. Si accende così, dalla cartella dello zip, e occupa il terminale: lascialo lì.
fastapi dev api/deposito.pyPer curl apri un secondo terminale. Su Windows, tutti e due sono terminali di Ubuntu (WSL).
curl
curl fa una richiesta e stampa la risposta. Da solo, è una GET:
curl http://127.0.0.1:8000/treni/M12{"tipo":"metro","vagoni":4,"stato":"in servizio","stazione":"Porta Codice","codice":"M12"}Solo il corpo. Le opzioni aggiungono il resto: si scrivono dopo curl, prima dell'indirizzo (o dopo, è uguale).
| Opzione | Cosa fa |
|---|---|
-i | Mostra anche la riga del codice (HTTP/1.1 200 OK) e gli header |
-s | Silenzioso: toglie la barra di avanzamento, utile quando passi la risposta a un altro comando |
-v | Mostra tutto, anche la richiesta che parte (righe con >) e la risposta (righe con <) |
-X VERBO | Sceglie il verbo: -X DELETE, -X PUT. Senza, è GET |
-H "Nome: valore" | Aggiunge un header alla richiesta |
-d 'corpo' | Manda un corpo. Con -d, curl passa da solo a POST |
Con -i vedi la risposta intera:
curl -i http://127.0.0.1:8000/treni/M99HTTP/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 codice (404) sta nella prima riga: senza -i non lo vedresti, e il messaggio da solo sembrerebbe una risposta normale. Quando provi una rotta, parti sempre con -i.
Gli indirizzi, tra virgolette
Un indirizzo con il punto di domanda (la query) va tra virgolette doppie. Senza, zsh (il terminale del Mac) prova a leggere il ? come un jolly dei nomi di file, e si ferma:
curl -i "http://127.0.0.1:8000/treni?tipo=tram"Dentro un indirizzo non ci sono spazi: lo spazio si scrive %20. Il filtro ?stato=in deposito diventa ?stato=in%20deposito.
Una POST: -X, -H, -d
Per aggiungere un treno la centrale vuole un corpo JSON e vuole sapere che è JSON, con l'header Content-Type. Il corpo va tra virgolette semplici, così le virgolette doppie del JSON restano com'è. Il comando è lungo: una barra rovesciata in fondo alla riga dice «continua sotto».
curl -i -X POST http://127.0.0.1:8000/treni \
-H "Content-Type: application/json" \
-d '{"codice": "M22", "tipo": "metro", "vagoni": 4}'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"}Quello che parte davvero è questo (lo vedresti con -v):
POST /treni HTTP/1.1
Host: 127.0.0.1:8000
Content-Type: application/json
{"codice": "M22", "tipo": "metro", "vagoni": 4}-X POST accanto a -d si può omettere (curl lo fa da solo). -X serve per gli altri verbi: PUT, DELETE.
Leggere il JSON in colonna
Il JSON su una riga sola si legge male. Dai la risposta a python3 -m json.tool, con una barra verticale | (che passa quello che stampa il primo comando al secondo):
curl -s "http://127.0.0.1:8000/treni?tipo=tram" | python3 -m json.tool[
{
"tipo": "tram",
"vagoni": 2,
"stato": "in servizio",
"stazione": "Ponte Ciclo",
"codice": "T05"
},
{
"tipo": "tram",
"vagoni": 3,
"stato": "in servizio",
"stazione": "Via Variabile",
"codice": "T28"
}
]Qui -s serve: senza, la barra di avanzamento di curl finirebbe in mezzo.
L'indirizzo in una variabile
Scrivere http://127.0.0.1:8000 in ogni comando stanca, e se il server cambia porta bisogna cambiarli tutti. Una variabile della shell risolve:
BASE_URL=http://127.0.0.1:8000
curl -i "$BASE_URL/treni/M12"$BASE_URL è sostituito dalla shell prima di lanciare curl. Gli esercizi della palestra lavorano così: nei file .sh la prima riga è BASE_URL="${BASE_URL:-http://127.0.0.1:8000}", che vuol dire «usa quello che c'è già, e se non c'è niente usa il server tuo». Il test mette il suo indirizzo, e il tuo comando funziona lo stesso.
Postman
Postman fa le stesse richieste di curl, con i bottoni al posto delle opzioni, e le salva. Con curl, la richiesta di ieri è nella cronologia del terminale; con Postman è lì, con il suo nome, pronta a ripartire.
Si usa l'app desktop (su Windows quella di Windows, non dentro Ubuntu: raggiunge lo stesso 127.0.0.1). La versione nel browser no: con un server sul tuo computer risponde Could not send request.
GET ▾ {{baseUrl}}/treni/M12 [ Send ]
Params · Authorization · Headers · Body · ScriptsUna richiesta, pezzo per pezzo:
- Il verbo: il menu a tendina a sinistra dell'indirizzo.
- L'indirizzo: la variabile
{{baseUrl}}più il percorso. La query la scrivi nell'indirizzo, o nella scheda Params. - Send: la richiesta parte. Sotto compaiono il codice, il corpo (Body) e gli header (Headers).
La collezione e la variabile
Una collezione è la cartella in cui tieni le richieste di un progetto. Si crea una volta:
- Collections → + → dai un nome, per esempio «Deposito Linea Menta».
- Nella collezione, scheda Variables: aggiungi
baseUrlcon valorehttp://127.0.0.1:8000, poi Save. - Sulla collezione, i tre puntini → Add request: una richiesta nuova, dentro la collezione.
- Dai un nome chiaro (per esempio «GET un treno · M12») e salva con Cmd+S (Mac) o Ctrl+S (Windows).
Quando l'API andrà online, cambia solo il valore di baseUrl: le richieste restano uguali. Se {{baseUrl}} resta rosso, la variabile non esiste in quella collezione.
Il corpo JSON
Per una POST o una PUT: scheda Body → raw → nel menu a destra scegli JSON (e non Text) → scrivi il corpo con le virgolette doppie.
{"codice": "M22", "tipo": "metro", "vagoni": 4}Scegliendo JSON, Postman aggiunge da solo l'header Content-Type: application/json: è la riga che con curl devi scrivere a mano. Se nel menu resta Text, la centrale risponde 422.
Il biglietto: Bearer e lo script
Le rotte protette (/me, /me/turni) vogliono il biglietto del login, come lo spiega Il biglietto (JWT). In curl è un header. In Postman è un campo: scheda Authorization → Auth Type → Bearer Token → nel campo Token scrivi {{biglietto}}.
Resta da riempire la variabile biglietto. Si può copiare a mano dalla risposta del login, ma il biglietto scade e a ogni riavvio del server va rifatto. Meglio far salvare il biglietto a Postman: nella richiesta del login (POST /login, Body raw JSON con badge e password), scheda Scripts → Post-response (lo script che parte dopo la risposta) scrivi:
pm.collectionVariables.set("biglietto", pm.response.json().access_token);Si legge così: «prendi la risposta, leggila come JSON, prendi access_token e mettilo nella variabile biglietto della collezione». Dopo ogni Send del login, la variabile si aggiorna. Per accorgertene: scheda Variables della collezione.
Poi nelle altre richieste basta Bearer Token con {{biglietto}}. In alternativa, imposta il Bearer una volta sola sulla collezione (scheda Authorization) e lascia le richieste su Inherit auth from parent.
Postman o la pagina /docs?
FastAPI ti regala /docs, dove puoi già provare le rotte. Servono tutti e due:
/docs | Postman | |
|---|---|---|
| Dove sta | Dentro l'API: c'è solo a server acceso | Fuori: è un client, come curl |
| Le richieste | Si riscrivono a ogni volta | Si salvano nella collezione, con i dati |
| L'indirizzo | Sempre quello del server | Una variabile: cambia in un posto |
| Va bene per | Provare una rotta al volo | Rifare le stesse richieste, o passarle a un collega |
curl sta in mezzo: niente da installare, un comando si copia in una chat e si mette in uno script (come nella palestra). Il confronto con il browser e con Python sta in Fare richieste.
Ricorda
- curl, nel terminale, e Postman, con l'app, sono client: mandano la richiesta che scrivi tu.
curl -imostra il codice e gli header: provando una rotta, parti da lì.- Con
-dscrivi anche-H "Content-Type: application/json"; il corpo tra virgolette semplici. - L'indirizzo va tra virgolette doppie, senza spazi (
%20). $BASE_URLin curl e{{baseUrl}}in Postman: l'indirizzo si scrive una volta sola.- Il biglietto va nell'header
Authorization: Bearer, e in Postman nello script post-response lo salvi nella variabilebiglietto.