2. curl dalla A alla Z
Obiettivi
Sezione intitolata “Obiettivi”- Usare
curlcon sicurezza per leggere (GET) e scrivere (POST/PUT/PATCH/DELETE) su un’API JSON. - Sapere cosa fa ogni opzione che vedrai nel corso, e riconoscerla negli esempi di qualunque documentazione.
- Padroneggiare la sintassi della shell che circonda curl: virgolette,
\per andare a capo, variabili, heredoc, pipe. - Formattare, salvare e ispezionare le risposte.
curl (client URL) esiste dal 1998, è preinstallato su Linux, macOS e Windows 10/11, e resta il modo più diretto per parlare con un’API: nessuna libreria, nessun linguaggio, solo la richiesta. Le opzioni sono tante (più di 250) ma per le API JSON ne bastano una ventina. Verifica la tua versione:
curl --version# curl 8.5.0 (x86_64-pc-linux-gnu) libcurl/8.5.0 OpenSSL/3.0.13 zlib/1.3 brotli/1.1.0 …La prima riga dice la versione (qui 8.5.0) e i protocolli/compressioni supportati. Serve almeno la 7.82 (marzo 2022) per l’opzione --json; con versioni più vecchie usi -H + -d, come vedremo.
Come si legge un comando curl
Sezione intitolata “Come si legge un comando curl”curl [opzioni] URL- Le opzioni corte hanno un trattino e una lettera (
-s,-X), quelle lunghe due trattini e una parola (--silent,--request). Sono equivalenti:-X POST=--request POST. - Alcune opzioni prendono un argomento (
-X POST,-H 'Accept: …'), altre no (-s,-i). Quelle senza argomento si possono fondere:-si=-s -i. - L’URL può stare ovunque, ma per leggibilità mettilo per ultimo.
- Un comando lungo si spezza su più righe con
\alla fine di ogni riga (niente spazi dopo il\).
Virgolette: la regola d’oro
Sezione intitolata “Virgolette: la regola d’oro”Le virgolette non le vede curl: le vede la shell, che le usa per capire dove inizia e finisce ogni argomento.
| Scrittura | Comportamento |
|---|---|
'…' singole |
testo letterale: $, ", \ restano come sono. Ideale per JSON: -d '{"title": "x"}' |
"…" doppie |
la shell espande $VARIABILI e $(comandi). Serve quando devi inserire un token: -H "Authorization: Bearer $TOKEN" |
| senza | solo per argomenti senza spazi né caratteri speciali (&, ?, * sono speciali!) |
Un URL con ? e & va sempre tra virgolette, altrimenti la shell interpreta & come “esegui in background” e il comando si spezza.
Le opzioni, una per una
Sezione intitolata “Le opzioni, una per una”1. Leggere: -s, -S, -i, -I, -v
Sezione intitolata “1. Leggere: -s, -S, -i, -I, -v”curl -sS -i 'https://corso-api-json.giuseppebosi.com/api/v1/books?limit=1'- -s
- silent: niente barra di avanzamento e niente messaggi
- -S
- show-error: ma se c'è un errore (DNS, connessione, TLS) mostralo comunque.
-sSè la coppia standard negli script - -i
- include: stampa anche riga di stato e header della risposta, prima del corpo
- 'https://…?limit=1'
- URL tra apici singoli perché contiene
?;limit=1è un parametro di query
HTTP/1.1 200 OKcontent-type: application/jsoncontent-length: 564x-request-id: 6d703371874fcache-control: no-store
{"items":[{"id":1,"title":"Il silenzio di Ustica",…}],"meta":{"page":1,"limit":1,"total":80,"pages":80},"links":{…}}Varianti:
-I(i maiuscola,--head) fa una richiestaHEAD: solo gli header, senza corpo. Attenzione: su questa API non funziona, perché FastAPI non crea rotteHEADe ogni/api/v1/...risponde405 Method Not Allowed. Provalo sulle pagine del sito (curl -s -I https://corso-api-json.giuseppebosi.com/); per vedere gli header dell’API usa-D - -o /dev/null, che fa unaGETnormale.-v(--verbose) mostra anche la richiesta (>), gli header ricevuti (<) e la negoziazione TLS. L’hai visto nel capitolo 1.-vvnon aggiunge nulla;--trace-ascii fileè il livello successivo.
2. Il metodo: -X
Sezione intitolata “2. Il metodo: -X”curl -sS -X POST https://corso-api-json.giuseppebosi.com/api/v1/sandbox- -X POST
- --request: usa il metodo
POSTinvece diGET. Vale perPUT,PATCH,DELETE,HEAD… - …/sandbox
- nessun corpo: questo endpoint non ne vuole. Risponde
201 Createdcon il token
{"token":"sb_7cyEmMkco216unjxIBct6XTQ","created_at":"2026-09-18T20:03:39Z","expires_at":"2026-09-19T02:03:39Z","how_to_use":{"header":"Authorization: Bearer sb_7cyEmMkco216unjxIBct6XTQ","alt_header":"X-Sandbox-Token: sb_7cyEmMkco216unjxIBct6XTQ"}}Header della risposta
3. Salvare un valore in una variabile: $(…)
Sezione intitolata “3. Salvare un valore in una variabile: $(…)”Il token va riusato in tutti i comandi successivi. In bash/zsh:
TOKEN=$(curl -sS -X POST https://corso-api-json.giuseppebosi.com/api/v1/sandbox | python3 -c 'import json,sys; print(json.load(sys.stdin)["token"])')echo "$TOKEN"- TOKEN=$( … )
- la shell esegue ciò che è tra parentesi e mette il suo output nella variabile
TOKEN. Niente spazi intorno a= - | python3 -c …
- la pipe manda il JSON a un mini script Python che stampa solo il campo
token. Con jq:| jq -r .token(-r= senza virgolette) - echo "$TOKEN"
- controllo: stampa
sb_…. Doppie virgolette perché vogliamo l'espansione
Da qui in poi $TOKEN vale nella sessione corrente del terminale (se lo chiudi, lo perdi: crea un’altra sandbox).
4. Gli header: -H
Sezione intitolata “4. Gli header: -H”curl -sS -H "Authorization: Bearer $TOKEN" https://corso-api-json.giuseppebosi.com/api/v1/sandbox/me- -H "Authorization: Bearer $TOKEN"
- --header: aggiunge un header alla richiesta, formato
Nome: valore. Doppie virgolette per espandere$TOKEN. Ripeti-Hper ogni header - /sandbox/me
- risponde 200 con chi sei, o 401 senza (o con) token sbagliato
{"authenticated":true,"token_prefix":"sb_7cyEm…","expires_at":"2026-09-19T02:03:39Z"}Altri header utili con -H: -H 'Accept: application/json', -H 'Content-Type: application/json', -H 'If-None-Match: "etag"'. Per togliere un header che curl mette da solo: -H 'User-Agent:' (nome e due punti, valore vuoto).
5. Il corpo: -d, --data-raw, --json
Sezione intitolata “5. Il corpo: -d, --data-raw, --json”curl -sS -X POST https://corso-api-json.giuseppebosi.com/api/v1/books \-H "Authorization: Bearer $TOKEN" \-H 'Content-Type: application/json' \-d '{"title": "Il mio primo libro", "author_id": 3, "category_id": 2, "price": 12.5}'- \ a fine riga
- continua il comando sulla riga dopo. Deve essere l'ultimo carattere della riga
- -H 'Content-Type: application/json'
- dice al server che il corpo è JSON. Senza, curl manda
application/x-www-form-urlencoded(il formato dei form HTML) e molti server rifiutano - -d '{…}'
- --data: il corpo della richiesta, tra apici singoli così le doppie virgolette del JSON restano intatte. Implica
POST
HTTP/1.1 201 Createdlocation: https://corso-api-json.giuseppebosi.com/api/v1/books/81
{"id":81,"title":"Il mio primo libro","isbn":"978-88-sandbox-81","author_id":3,"category_id":2,"price":12.5,…}Tre dettagli su -d:
-d @file.jsonlegge il corpo da un file (@= “dal file”).-d @-lo legge dallo standard input.-drimuove gli a capo dal dato;--data-rawlo manda com’è e non interpreta@. Per JSON è indifferente; se il tuo corpo inizia con@, usa--data-raw.- Con curl ≥ 7.82,
--json '{…}'è la scorciatoia per-d '{…}' -H 'Content-Type: application/json' -H 'Accept: application/json'. Comodo, ma negli esempi del corso useremo la forma esplicita, che funziona ovunque.
6. Corpi lunghi: heredoc
Sezione intitolata “6. Corpi lunghi: heredoc”Per un JSON su più righe, evita di lottare con le virgolette: usa un heredoc e -d @-.
curl -sS -X POST https://corso-api-json.giuseppebosi.com/api/v1/orders \-H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \-d @- <<'EOF'{"customer_id": 1,"items": [{"book_id": 5, "quantity": 2}, {"book_id": 9, "quantity": 1}],"shipping_address": {"street": "Via Roma 1", "city": "Milano", "zip": "20100"}}EOF- -d @-
- leggi il corpo dallo standard input
- <<'EOF'
- heredoc: tutto ciò che segue, fino alla riga
EOF, va nello standard input. Con'EOF'tra apici la shell non tocca il contenuto (niente espansione di$) - EOF
- la riga che chiude l'heredoc: da sola, senza spazi prima
Risposta: 201 Created con l’ordine completo di items e total. (Lo rifaremo con calma nel capitolo 6.)
7. Parametri di query: -G e --data-urlencode
Sezione intitolata “7. Parametri di query: -G e --data-urlencode”Scrivere a mano ?q=le%20estati&limit=5 è fragile. Lascia che curl codifichi:
curl -sS -G https://corso-api-json.giuseppebosi.com/api/v1/books \--data-urlencode 'q=le estati' --data-urlencode 'limit=5' --data-urlencode 'sort=-price'- -G
- --get: i dati passati con
-d/--data-urlencodevanno nella query string invece che nel corpo (e il metodo resta GET) - --data-urlencode 'q=le estati'
- codifica il valore: lo spazio diventa
%20. Una opzione per parametro. L'URL finale è/books?q=le%20estati&limit=5&sort=-price
8. Salvare la risposta: -o, -O
Sezione intitolata “8. Salvare la risposta: -o, -O”curl -sS -o libri.csv https://corso-api-json.giuseppebosi.com/api/v1/export/books.csvhead -3 libri.csv- -o libri.csv
- --output: scrive il corpo nel file invece che sul terminale
- -O
- (non usato qui) --remote-name: salva con il nome preso dall'URL, cioè
books.csv - head -3
- mostra le prime 3 righe del file
id,title,isbn,author_id,category_id,price,pages,published_year,language,in_stock,attributes,created_at,author_name,category1,Il silenzio di Ustica,978-88-81482-001-1,19,2,18.71,120,2002,it,1,"{""format"": ""brossura"", …}",2025-06-01T00:00:00Z,Laura Esposito,gialli2,TypeScript e Ferrara,978-88-30379-002-3,11,9,9.76,479,2013,it,1,"{…}",2024-12-18T00:00:00Z,Beatrice Colombo,informatica-o /dev/null butta via il corpo: lo si usa quando interessa solo lo status (punto 9).
9. Solo lo status: -w e -o /dev/null
Sezione intitolata “9. Solo lo status: -w e -o /dev/null”curl -sS -o /dev/null -w '%{http_code} %{time_total}s %{size_download} byte\n' \https://corso-api-json.giuseppebosi.com/api/v1/books/9999- -o /dev/null
- scarta il corpo
- -w '…'
- --write-out: dopo la richiesta stampa la stringa data, sostituendo le variabili
%{…}:http_code(status),time_total(secondi),size_download(byte del corpo).\nmette l'a capo finale
404 0.031s 65 bytePerfetto negli script: if [ "$(curl -s -o /dev/null -w '%{http_code}' URL)" = "200" ]; then ….
10. Redirect, compressione, timeout, retry, User-Agent
Sezione intitolata “10. Redirect, compressione, timeout, retry, User-Agent”curl -sS -L --compressed --max-time 10 --retry 3 --retry-delay 2 \-A 'corso-json/1.0' -o /dev/null -w '%{http_code}\n' \https://corso-api-json.giuseppebosi.com/json/01-cos-e-json- -L
- --location: segue i redirect (3xx). Senza, curl si ferma al 307 e mostra un corpo vuoto. Qui
/json/01-cos-e-jsonredirige alla versione con/finale - --compressed
- chiede la risposta compressa (
Accept-Encoding: gzip, br, zstd) e la decomprime. Meno byte sul filo - --max-time 10
- abbandona dopo 10 secondi totali (c'è anche
--connect-timeoutper la sola connessione) - --retry 3 --retry-delay 2
- riprova fino a 3 volte, aspettando 2 s, su errori transitori (timeout, 5xx, 429). Non riprova su 4xx normali
- -A 'corso-json/1.0'
- --user-agent: come ti presenti. Le API pubbliche spesso chiedono un UA identificabile
20011. Autenticazione HTTP Basic: -u
Sezione intitolata “11. Autenticazione HTTP Basic: -u”Non serve per questo server (usa Bearer), ma la troverai in molte API: -u utente:password aggiunge Authorization: Basic <base64>. Con -u utente (senza password) curl la chiede in modo interattivo, così non finisce nella cronologia della shell.
12. Formattare e filtrare: python3 -m json.tool e jq
Sezione intitolata “12. Formattare e filtrare: python3 -m json.tool e jq”curl -sS 'https://corso-api-json.giuseppebosi.com/api/v1/books?limit=3' | jq '.items[] | {id, title, price}'- | jq
jqè un processore JSON da riga di comando (da installare:apt install jq,brew install jq,winget install jqlang.jq)- '.items[] | {id, title, price}'
- programma jq: prendi la chiave
items, itera l'array ([]), e per ogni elemento costruisci un oggetto con solo quei tre campi
{ "id": 1, "title": "Il silenzio di Ustica", "price": 18.71 }{ "id": 2, "title": "TypeScript e Ferrara", "price": 9.76 }{ "id": 3, "title": "Il cervello e Matera", "price": 31.16 }Senza jq: | python3 -m json.tool riformatta tutto (nessun filtro), ed è già installato ovunque ci sia Python. Nel capitolo 10 della Sezione 1 jq è trattato a fondo.
Prova subito
Sezione intitolata “Prova subito”Il pulsante Copia come curl di ogni widget del corso genera il comando equivalente con le opzioni che hai appena imparato (-i -X -H -d):
Header della risposta
Esercizio
Sezione intitolata “Esercizio”Scrivi un solo comando curl che: (a) chieda i libri della categoria cucina ordinati per prezzo crescente, massimo 5, codificando i parametri con --data-urlencode; (b) mostri gli header della risposta; (c) stampi alla fine il tempo totale. Poi un secondo comando che salvi lo stesso risultato in cucina.json e stampi solo lo status.
Soluzione
curl -sS -i -G https://corso-api-json.giuseppebosi.com/api/v1/books \ --data-urlencode 'category=cucina' --data-urlencode 'sort=price' --data-urlencode 'limit=5' \ -w '\ntempo: %{time_total}s\n'
curl -sS -G https://corso-api-json.giuseppebosi.com/api/v1/books \ --data-urlencode 'category=cucina' --data-urlencode 'sort=price' --data-urlencode 'limit=5' \ -o cucina.json -w '%{http_code}\n'Il secondo stampa 200 e crea cucina.json (verifica con python3 -m json.tool cucina.json | head).
Errori comuni
Sezione intitolata “Errori comuni”- URL senza virgolette con
&:curl …/books?a=1&b=2→ la shell manda in background curl cona=1e poi esegueb=2. Metti l’URL tra'…'. $TOKENtra apici singoli:-H 'Authorization: Bearer $TOKEN'manda letteralmente la stringa$TOKEN→ 401. Usa le doppie.- Spazio dopo
\a fine riga: la riga successiva viene eseguita come comando a sé. - Dimenticare
-Le credere che la risposta sia vuota: era un redirect. -dsenzaContent-Type: il server riceve un form, non JSON → 422.- Corpo JSON con apici singoli o virgola finale: non è JSON valido; il server risponde 422 con
code: "validation_error"e, dentrodetails[0],type: "json_invalid"e la posizione.
In sintesi
Sezione intitolata “In sintesi”-sS per pulizia, -i/-v per vedere, -X per il metodo, -H per gli header, -d (+ Content-Type) per il corpo, -G --data-urlencode per la query, -o/-w per salvare e misurare, -L --compressed --max-time --retry per la robustezza. E la shell fa la sua parte: apici singoli per il JSON, doppi per le variabili. Il cheatsheet raccoglie tutto in una pagina. Prossimo capitolo: lo stesso GET, ma da Python e TypeScript.