Salta ai contenuti

14. JSON e HTTP

  • Riconoscere gli header che governano JSON in HTTP: Content-Type, Accept, Content-Length, Location.
  • Inviare JSON in un body POST e 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.

  • 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). Fare r.json() qui è un errore.
  • 400 Bad Request — richiesta malformata (parametro sconosciuto, expand non 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.

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.

Prima uno sguardo agli header di una risposta JSON:

terminale
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 OK
content-type: application/json
content-length: 362
etag: "fd261646a574ca77"
cache-control: public, max-age=60
x-request-id: c67b48c823ac

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

terminale
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 token come testo grezzo (senza virgolette)
-X POST
metodo POST
-H "Authorization: Bearer $TOKEN"
header di autenticazione; tra doppi apici perché $TOKEN deve 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)?

Finestra del terminale
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:

terminale
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 (-i ignora maiuscole, -E regex estesa)
-X DELETE
metodo DELETE sulla risorsa creata (l'id 81 è quello restituito dal POST nella sandbox)
HTTP/1.1 201 Created
content-type: application/json
location: https://corso-api-json.giuseppebosi.com/api/v1/books/81
HTTP/1.1 204 No Content

A volte serve passare una struttura in un GET. Va URL-encoded: {, ", spazi e caratteri non ASCII non possono stare nudi in un URL.

terminale
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-urlencode nella 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.

import json, httpx
BASE = "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 solo
r = httpx.post(f"{BASE}/books", json={"title": "", "author_id": "uno", "price": -3}, headers=auth)
print(r.status_code, r.headers["content-type"]) # 422 application/json
for d in r.json()["error"]["details"]:
print("/".join(map(str, d["loc"])), "→", d["msg"])
# creazione: 201 + Location
r = 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/81
nuovo = r.json()
# 204: nessun corpo. r.json() qui solleverebbe JSONDecodeError
r = 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%7D
print(r.json()["query"]) # {'filtro': '{"città": "Roma", "max": 10}'}
# l'errore classico: data= invia un form, non JSON
r = 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 from

Cosa dovresti vedere:

422 application/json
body/title → String should have at least 1 character
body/author_id → Input should be a valid integer, unable to parse string as an integer
body/category_id → Field required
body/price → Input should be greater than or equal to 0
201 https://corso-api-json.giuseppebosi.com/api/v1/books/81
204 ''
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
POST/api/v1/echo?a=1&b=due— l'echo: guarda headers.content-type e json nella risposta
POST/api/v1/books— un 422 con quattro errori (serve la sandbox)
Serve un token sandbox: crealo dal pannello La tua sandbox (viene salvato nel browser).
POST/api/v1/books— un 201: guarda l'header Location
Serve un token sandbox: crealo dal pannello La tua sandbox (viene salvato nel browser).

Provalo online, senza installare nulla:

Apri il notebook in Google Colab Apri il progetto TypeScript in StackBlitz

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:

  1. Cosa contiene json nella risposta se mandi un body con Content-Type: text/plain?
  2. Cosa succede all’header Content-Length se mandi un body vuoto con -X POST?
  3. Manda un body con caratteri accentati e emoji e controlla che tornino intatti.
Soluzione
Finestra del terminale
curl -s -X POST …/api/v1/echo -H 'Content-Type: text/plain' -d '{"a":1}' | jq .json # 1
curl -s -X POST …/api/v1/echo -H 'Content-Length: 0' | jq '.headers["content-length"]' # 2
curl -s -X POST …/api/v1/echo -H 'Content-Type: application/json' -d '{"s":"caffè ☕"}' | jq .json # 3
  1. /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.
  • fetch senza Content-Type (vedi sopra) e, specularmente, httpx.post(data=...) invece di json=....
  • r.json() su un 204 o su una risposta di errore HTML (proxy, pagina di manutenzione): controlla prima content-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=, URLSearchParams esistono per questo.

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.