14. JSON e HTTP
Obiettivi
Sezione intitolata “Obiettivi”- Riconoscere gli header che governano JSON in HTTP:
Content-Type,Accept,Content-Length,Location. - Inviare JSON in un body
POSTe leggere una risposta di errore strutturata. - Distinguere 200/201/204/400/422 e sapere cosa contengono (o non contengono).
- Passare JSON in una query string senza romperlo (URL encoding).
Un messaggio HTTP ha riga di stato/richiesta, header e un body opzionale. JSON vive nel body; gli header dicono come interpretarlo.
| Header | Nella richiesta | Nella risposta |
|---|---|---|
Content-Type: application/json |
“il body che ti mando è JSON” (obbligatorio per POST/PUT/PATCH) | “il body che ti restituisco è JSON” |
Accept: application/json |
“voglio JSON in risposta” (content negotiation) | — |
Content-Length / Transfer-Encoding: chunked |
lunghezza del body, o invio a pezzi | idem |
Location |
— | nelle 201: URL della risorsa appena creata |
Sul charset: RFC 8259 impone UTF-8 e dice che application/json non ha un parametro charset; lo vedrai comunque (application/json; charset=utf-8) ed è innocuo.
Status code e corpo
Sezione intitolata “Status code e corpo”- 200 OK — corpo JSON con la risorsa o la lista.
- 201 Created — creazione riuscita; corpo con la risorsa creata e header
Location. - 204 No Content — riuscito, nessun corpo (tipico di
DELETE). Farer.json()qui è un errore. - 400 Bad Request — richiesta malformata (parametro sconosciuto,
expandnon valido…). - 422 Unprocessable Content — sintassi ok ma dati non validi: il server dice quale campo e perché.
- 401 / 404 / 409 / 429 — li vedrai nella Sezione 2, capitolo 7.
Il formato degli errori
Sezione intitolata “Il formato degli errori”Un’API seria risponde agli errori sempre con la stessa forma, così il client la gestisce in un solo punto. Questa API usa:
{ "error": { "code": "validation_error", "message": "…", "details": [ … ] } }code è per il programma (stabile, confrontabile), message per l’umano, details opzionale con i particolari.
curl, spiegato
Sezione intitolata “curl, spiegato”Prima uno sguardo agli header di una risposta JSON:
curl -si https://corso-api-json.giuseppebosi.com/api/v1/books/1 | head -8- -i
- include: stampa anche gli header della risposta prima del corpo
- head -8
- solo le prime 8 righe: riga di stato + header
HTTP/1.1 200 OKcontent-type: application/jsoncontent-length: 362etag: "fd261646a574ca77"cache-control: public, max-age=60x-request-id: c67b48c823acOra un POST con body volutamente sbagliato, per vedere un 422. Le scritture richiedono una sandbox: il token si ottiene con POST /api/v1/sandbox (dettagli nella Sezione 2, capitolo 6).
TOKEN=$(curl -s -X POST https://corso-api-json.giuseppebosi.com/api/v1/sandbox | jq -r .token)
curl -s -X POST https://corso-api-json.giuseppebosi.com/api/v1/books \-H "Authorization: Bearer $TOKEN" \-H 'Content-Type: application/json' \-d '{"title": "", "author_id": "uno", "price": -3}' | jq .- TOKEN=$( … )
- esegue il comando tra parentesi e mette il suo output nella variabile
- jq -r .token
- estrae il campo
tokencome testo grezzo (senza virgolette) - -X POST
- metodo POST
- -H "Authorization: Bearer $TOKEN"
- header di autenticazione; tra doppi apici perché
$TOKENdeve essere espanso - -H 'Content-Type: application/json'
- dice al server come leggere il body
- -d '…'
- il body JSON; tra apici singoli così le virgolette doppie restano
{ "error": { "code": "validation_error", "message": "Richiesta non valida: controlla i campi in details", "details": [ { "loc": ["body", "title"], "msg": "String should have at least 1 character", "type": "string_too_short" }, { "loc": ["body", "author_id"], "msg": "Input should be a valid integer, unable to parse string as an integer", "type": "int_parsing" }, { "loc": ["body", "category_id"], "msg": "Field required", "type": "missing" }, { "loc": ["body", "price"], "msg": "Input should be greater than or equal to 0", "type": "greater_than_equal" } ] }}Quattro errori in una sola risposta, ognuno con il percorso del campo (loc). E se il body non è nemmeno JSON valido (virgola finale)?
curl -s -X POST …/api/v1/books -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' -d '{"title": "x",}'# {"error":{"code":"validation_error","message":"…","details":[{"loc":["body",14],"msg":"JSON decode error","type":"json_invalid"}]}}loc: ["body", 14]: l’errore è al carattere 14 del body. Infine una creazione riuscita e una cancellazione:
curl -si -X POST https://corso-api-json.giuseppebosi.com/api/v1/books \-H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \-d '{"title":"Prova JSON","author_id":1,"category_id":9,"price":9.9,"attributes":{"format":"tascabile"}}' \| grep -iE '^(HTTP|content-type|location)'
curl -si -X DELETE "https://corso-api-json.giuseppebosi.com/api/v1/books/81" -H "Authorization: Bearer $TOKEN" | head -1- grep -iE '^(HTTP|content-type|location)'
- filtra le righe che iniziano con uno di quei tre nomi (
-iignora maiuscole,-Eregex estesa) - -X DELETE
- metodo DELETE sulla risorsa creata (l'id 81 è quello restituito dal POST nella sandbox)
HTTP/1.1 201 Createdcontent-type: application/jsonlocation: https://corso-api-json.giuseppebosi.com/api/v1/books/81
HTTP/1.1 204 No ContentJSON nella query string
Sezione intitolata “JSON nella query string”A volte serve passare una struttura in un GET. Va URL-encoded: {, ", spazi e caratteri non ASCII non possono stare nudi in un URL.
curl -s -G https://corso-api-json.giuseppebosi.com/api/v1/echo \--data-urlencode 'filtro={"città":"Roma","max":10}' | jq .query- -G
- manda i dati di
-d/--data-urlencodenella query string di una GET invece che nel body - --data-urlencode 'k=v'
- codifica il valore per l'URL:
{→%7B,"→%22,à→%C3%A0 - /echo
- endpoint didattico che rimanda ciò che riceve
{ "filtro": "{\"città\":\"Roma\",\"max\":10}" }Il server ha ricevuto la stringa intatta; sta a lui farne json.loads. Per strutture non banali, però, preferisci un POST con body JSON (come /query): più leggibile, nessun limite di lunghezza dell’URL.
Python e TypeScript
Sezione intitolata “Python e TypeScript”import json, httpxBASE = "https://corso-api-json.giuseppebosi.com/api/v1"
token = httpx.post(f"{BASE}/sandbox").json()["token"]auth = {"Authorization": f"Bearer {token}"}
# json= serializza il dict e imposta Content-Type: application/json da solor = httpx.post(f"{BASE}/books", json={"title": "", "author_id": "uno", "price": -3}, headers=auth)print(r.status_code, r.headers["content-type"]) # 422 application/jsonfor d in r.json()["error"]["details"]: print("/".join(map(str, d["loc"])), "→", d["msg"])
# creazione: 201 + Locationr = httpx.post(f"{BASE}/books", headers=auth, json={"title": "Prova JSON", "author_id": 1, "category_id": 9, "price": 9.9, "attributes": {"format": "tascabile"}})print(r.status_code, r.headers["location"]) # 201 https://…/api/v1/books/81nuovo = r.json()
# 204: nessun corpo. r.json() qui solleverebbe JSONDecodeErrorr = httpx.delete(f"{BASE}/books/{nuovo['id']}", headers=auth)print(r.status_code, repr(r.text)) # 204 ''
# JSON nella query string: httpx codifica i params per te (ensure_ascii=False tiene la à leggibile)r = httpx.get(f"{BASE}/echo", params={"filtro": json.dumps({"città": "Roma", "max": 10}, ensure_ascii=False)})print(r.url) # …/echo?filtro=%7B%22citt%C3%A0%22%3A+%22Roma%22%2C+%22max%22%3A+10%7Dprint(r.json()["query"]) # {'filtro': '{"città": "Roma", "max": 10}'}
# l'errore classico: data= invia un form, non JSONr = httpx.post(f"{BASE}/books", data={"title": "x"}, headers=auth)print(r.json()["error"]["details"][0]["msg"]) # Input should be a valid dictionary or object to extract fields fromCosa dovresti vedere:
422 application/jsonbody/title → String should have at least 1 characterbody/author_id → Input should be a valid integer, unable to parse string as an integerbody/category_id → Field requiredbody/price → Input should be greater than or equal to 0201 https://corso-api-json.giuseppebosi.com/api/v1/books/81204 ''https://corso-api-json.giuseppebosi.com/api/v1/echo?filtro=%7B%22citt%C3%A0%22%3A+%22Roma%22%2C+%22max%22%3A+10%7D{'filtro': '{"città": "Roma", "max": 10}'}Input should be a valid dictionary or object to extract fields from// node --experimental-strip-types http.tsconst BASE = "https://corso-api-json.giuseppebosi.com/api/v1";const { token } = await (await fetch(`${BASE}/sandbox`, { method: "POST" })).json();const auth = { Authorization: `Bearer ${token}` };
// fetch NON imposta Content-Type per te: va dichiarato, e il body va serializzato a manolet r = await fetch(`${BASE}/books`, { method: "POST", headers: { ...auth, "Content-Type": "application/json" }, body: JSON.stringify({ title: "", author_id: "uno", price: -3 }),});console.log(r.status, r.headers.get("content-type")); // 422 application/jsonconst err = await r.json();for (const d of err.error.details) console.log(d.loc.join("/"), "→", d.msg);
// 201 + Locationr = await fetch(`${BASE}/books`, { method: "POST", headers: { ...auth, "Content-Type": "application/json" }, body: JSON.stringify({ title: "Prova JSON", author_id: 1, category_id: 9, price: 9.9, attributes: { format: "tascabile" } }),});console.log(r.status, r.headers.get("location"));const nuovo = await r.json();
// 204: niente corpo → non chiamare r.json()r = await fetch(`${BASE}/books/${nuovo.id}`, { method: "DELETE", headers: auth });console.log(r.status, JSON.stringify(await r.text())); // 204 ""
// JSON nella query string con URLSearchParams (fa l'encoding)const qs = new URLSearchParams({ filtro: JSON.stringify({ città: "Roma", max: 10 }) });console.log(qs.toString()); // filtro=%7B%22citt%C3%A0%22%3A%22Roma%22%2C%22max%22%3A10%7Dr = await fetch(`${BASE}/echo?${qs}`);console.log((await r.json()).query); // { filtro: '{"città":"Roma","max":10}' }
// l'errore classico: body senza Content-Typer = await fetch(`${BASE}/books`, { method: "POST", headers: auth, body: JSON.stringify({ title: "x" }) });console.log(r.status, (await r.json()).error.details[0].msg); // 422 Input should be a valid dictionary or object…Cosa dovresti vedere:
422 application/jsonbody/title → String should have at least 1 characterbody/author_id → Input should be a valid integer, unable to parse string as an integerbody/category_id → Field requiredbody/price → Input should be greater than or equal to 0201 https://corso-api-json.giuseppebosi.com/api/v1/books/81204 ""filtro=%7B%22citt%C3%A0%22%3A%22Roma%22%2C%22max%22%3A10%7D{ filtro: '{"città":"Roma","max":10}' }422 Input should be a valid dictionary or object to extract fields fromDimenticare "Content-Type": "application/json" con fetch è l’errore più frequente in assoluto: il server riceve una stringa senza sapere che è JSON e risponde 422.
Prova subito
Sezione intitolata “Prova subito”Header della risposta
Header della risposta
Header della risposta
Esercizio
Sezione intitolata “Esercizio”Provalo online, senza installare nulla:
Python su Google Colab (serve un account Google gratuito per eseguire le celle); TypeScript su StackBlitz (si apre e parte da solo nel browser). Se l’API di prova è spenta, accendila da /api-attiva/.
Con /echo (accetta GET, POST e PUT), verifica sperimentalmente:
- Cosa contiene
jsonnella risposta se mandi un body conContent-Type: text/plain? - Cosa succede all’header
Content-Lengthse mandi un body vuoto con-X POST? - Manda un body con caratteri accentati e emoji e controlla che tornino intatti.
Soluzione
curl -s -X POST …/api/v1/echo -H 'Content-Type: text/plain' -d '{"a":1}' | jq .json # 1curl -s -X POST …/api/v1/echo -H 'Content-Length: 0' | jq '.headers["content-length"]' # 2curl -s -X POST …/api/v1/echo -H 'Content-Type: application/json' -d '{"s":"caffè ☕"}' | jq .json # 3/echoè permissivo e prova comunque a fare il parsing: ottieni{"a": 1}. Un endpoint normale (come/books) invece rifiuterebbe con 422. 2."0". 3. Torna{"s": "caffè ☕"}: JSON è UTF-8 end-to-end.
Errori comuni
Sezione intitolata “Errori comuni”fetchsenzaContent-Type(vedi sopra) e, specularmente,httpx.post(data=...)invece dijson=....r.json()su un 204 o su una risposta di errore HTML (proxy, pagina di manutenzione): controlla primacontent-type.- Trattare 4xx come eccezioni “generiche”: leggi
error.code, è lì per essere confrontato. - JSON nell’URL senza encoding: lo spazio e
"spezzano l’URL;--data-urlencode,params=,URLSearchParamsesistono per questo.
In sintesi
Sezione intitolata “In sintesi”Il body porta il JSON, gli header dicono cos’è, lo status dice com’è andata, e gli errori hanno una forma fissa che il client sfrutta. Ultimo capitolo della sezione: mettere tutto insieme in un progetto.