Vai al contenuto
code-to-code

Apro l'indice…

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

Il banco di lavoro6. Postman e curlp. 132

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 JSON

Il 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ì.

Terminale
fastapi dev api/deposito.py

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

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

OpzioneCosa fa
-iMostra anche la riga del codice (HTTP/1.1 200 OK) e gli header
-sSilenzioso: toglie la barra di avanzamento, utile quando passi la risposta a un altro comando
-vMostra tutto, anche la richiesta che parte (righe con >) e la risposta (righe con <)
-X VERBOSceglie 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:

Terminale
curl -i http://127.0.0.1:8000/treni/M99
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 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:

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

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

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

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

Terminale
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 · Scripts

Una richiesta, pezzo per pezzo:

  1. Il verbo: il menu a tendina a sinistra dell'indirizzo.
  2. L'indirizzo: la variabile {{baseUrl}} più il percorso. La query la scrivi nell'indirizzo, o nella scheda Params.
  3. 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:

  1. Collections → + → dai un nome, per esempio «Deposito Linea Menta».
  2. Nella collezione, scheda Variables: aggiungi baseUrl con valore http://127.0.0.1:8000, poi Save.
  3. Sulla collezione, i tre puntini → Add request: una richiesta nuova, dentro la collezione.
  4. 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.

JSON
{"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:

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

/docsPostman
Dove staDentro l'API: c'è solo a server accesoFuori: è un client, come curl
Le richiesteSi riscrivono a ogni voltaSi salvano nella collezione, con i dati
L'indirizzoSempre quello del serverUna variabile: cambia in un posto
Va bene perProvare una rotta al voloRifare 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 -i mostra il codice e gli header: provando una rotta, parti da lì.
  • Con -d scrivi anche -H "Content-Type: application/json"; il corpo tra virgolette semplici.
  • L'indirizzo va tra virgolette doppie, senza spazi (%20).
  • $BASE_URL in 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 variabile biglietto.