10. JSON annidati e navigazione
Obiettivi
Sezione intitolata “Obiettivi”- Leggere valori a tre o quattro livelli di profondità senza
KeyError/TypeError. - Usare jq dal terminale per esplorare, filtrare e trasformare JSON.
- Conoscere JSONPath per esprimere percorsi in modo dichiarativo.
- Capire come un’API produce JSON annidati “seguendo” le chiavi esterne (
?expand=).
Un JSON reale non è mai piatto. L’ordine 1 con il cliente e i libri delle sue righe è un albero a quattro livelli: ordine → righe → libro → autore. Per arrivare al nome dell’autore del primo libro il percorso è items[0].book.author_name.
Tre modi per percorrere un albero:
- Accesso diretto (
o["items"][0]["book"]["author_name"]): veloce, ma se un pezzo manca il programma si ferma con un’eccezione. - Accesso sicuro:
.get()con default in Python,?.(optional chaining) e??in TypeScript. RestituisceNone/undefinedinvece di esplodere. - Un linguaggio di percorsi: JSONPath (
$.items[*].book.title) o jq (.items[].book.title). Ideale per esplorare dati sconosciuti o per script da terminale.
Come nasce un JSON annidato? Il database ha tabelle separate legate da chiavi esterne (orders.customer_id → customers.id, order_items.book_id → books.id). Il server, se glielo chiedi con ?expand=, sostituisce l’id con l’oggetto intero. Senza expand ricevi solo customer_id: 39 e devi fare una seconda richiesta: lo vedrai bene nella Sezione 2, capitolo 5.
curl, spiegato
Sezione intitolata “curl, spiegato”curl -s 'https://corso-api-json.giuseppebosi.com/api/v1/orders/1?expand=items.book,customer' | jq .- '…?expand=items.book,customer'
- l'URL sta tra apici singoli perché contiene
?e,, che la shell potrebbe interpretare - ?expand=
- inizio della query string: parametri
chiave=valoredopo il percorso - items.book
- espandi le righe (
items) e, dentro ogni riga, il libro referenziato dabook_id - ,customer
- più valori per lo stesso parametro, separati da virgola: espandi anche il cliente
- | jq .
.è il programma jq "identità": stampa il JSON com'è, ma indentato e colorato
{ "id": 1, "customer_id": 39, "status": "delivered", "shipping_address": { "street": "Via Sestri 73", "city": "Bari", "zip": "15399", "country": "IT" }, "total": 12.04, "created_at": "2025-01-10T21:00:00Z", "customer": { "id": 39, "name": "Giovanni Costa", "email": "giovanni.costa39@example.com", "city": "Bari", "created_at": "2025-04-27T00:00:00Z" }, "items": [ { "id": 1, "order_id": 1, "book_id": 11, "quantity": 1, "unit_price": 12.04, "book": { "id": 11, "title": "Quello che resta di Montecarvo", "price": 12.04, "author_id": 14, "author_name": "Pietro Galli" } } ]}jq in otto mosse
Sezione intitolata “jq in otto mosse”Lavoriamo sulla lista dei libri (/api/v1/books?limit=100, un oggetto con items e meta).
URL='https://corso-api-json.giuseppebosi.com/api/v1/books?limit=100'
# 1. proiezione: da ogni libro tieni solo due campicurl -s "$URL" | jq '.items[] | {title, price}'
# 2. filtro + conteggiocurl -s "$URL" | jq '[.items[] | select(.price < 8)] | length'
# 3. ordina, prendi i primi 3, stampa testo grezzo (-r) con tabcurl -s "$URL" | jq -r '.items | sort_by(-.price) | .[0:3][] | "\(.price)\t\(.title)"'
# 4. variabile dalla shell con --argcurl -s "$URL" | jq --arg f tascabile '[.items[] | select(.attributes.format == $f) | .title] | length'
# 5. appiattisci array annidati e raggruppacurl -s "$URL" | jq '[.items[].attributes.awards[]] | group_by(.) | map({premio: .[0], libri: length})'
# 6. accesso sicuro: una chiave che non esiste vale null, non errorecurl -s 'https://corso-api-json.giuseppebosi.com/api/v1/books/1' | jq '.attributes.dimensions_cm.h, .attributes.missing'
# 7. aggregazione numericacurl -s "$URL" | jq '.items | map(.price) | add / length | . * 100 | round / 100'- URL='…'
- variabile di shell; poi
"$URL"tra doppi apici, così viene espansa ma?e&restano protetti - .items[]
- entra in
itemse "scompatta" l'array: da qui in poi jq lavora un elemento alla volta - {title, price}
- costruisce un oggetto con quelle due chiavi (scorciatoia di
{title: .title, price: .price}) - [ … ]
- raccoglie di nuovo gli elementi in un array (serve per
length,sort_by…) - select(cond)
- lascia passare solo gli elementi per cui la condizione è vera
- -r
- raw: le stringhe escono senza virgolette (utile per tabelle e script)
- "\(.price)\t\(.title)"
- interpolazione:
\( )inserisce un'espressione dentro una stringa;\tè un tab - --arg f tascabile
- passa un valore dalla shell come variabile
$f(stringa); per numeri/JSON usa--argjson - .attributes.awards[]
[]su un array lo scompatta: i premi di tutti i libri finiscono in un unico flusso- group_by(.) | map(…)
- raggruppa valori uguali, poi trasforma ogni gruppo in un oggetto
- .a, .b
- la virgola produce più output: uno per espressione
- add / length
- somma degli elementi diviso il loro numero = media
Output (uno per comando):
{ "title": "Il silenzio di Ustica", "price": 18.71 } … (80 oggetti)334.49 Quello che resta di Sestri34.36 Ustica e il Novecento33.49 La cucina di Ustica30[ { "premio": "Bancarella", "libri": 10 }, { "premio": "Campiello", "libri": 8 }, { "premio": "Strega", "libri": 14 }, { "premio": "Viareggio", "libri": 16 } ]19null19.9Python e TypeScript
Sezione intitolata “Python e TypeScript”# pip install httpx jsonpath-ngimport httpxfrom jsonpath_ng.ext import parse
BASE = "https://corso-api-json.giuseppebosi.com/api/v1"o = httpx.get(f"{BASE}/orders/1", params={"expand": "items.book,customer"}).json()
# accesso diretto: chiaro, ma KeyError se manca un pezzoprint(o["items"][0]["book"]["author_name"]) # Pietro Galli
# accesso sicuro: .get() a catena con defaultprint(o.get("customer", {}).get("city")) # Bariprint(o.get("customer", {}).get("phone", "n/d")) # n/d (campo inesistente)
# JSONPath: percorsi dichiarativi, anche con wildcard e filtriprint([m.value for m in parse("$.items[*].book.title").find(o)])print([m.value for m in parse("$.items[?(@.quantity>=1)].book.author_name").find(o)])
lista = httpx.get(f"{BASE}/books", params={"limit": 100}).json()economici = [m.value for m in parse("$.items[?(@.price<8)].title").find(lista)]print(len(economici)) # 3Cosa dovresti vedere:
Pietro GalliBarin/d['Quello che resta di Montecarvo']['Pietro Galli']3Note: jsonpath_ng.ext (non jsonpath_ng) serve per i filtri [?(...)]. Per un percorso fisso su cui non serve flessibilità, .get() a catena è più leggibile e più veloce.
// node --experimental-strip-types naviga.tsconst BASE = "https://corso-api-json.giuseppebosi.com/api/v1";const o = await (await fetch(`${BASE}/orders/1?expand=items.book,customer`)).json();
// accesso diretto: TypeError se un pezzo è undefinedconsole.log(o.items[0].book.author_name); // Pietro Galli
// optional chaining ?. e nullish coalescing ??console.log(o.customer?.city); // Bariconsole.log(o.customer?.phone ?? "n/d"); // n/dconsole.log(o.items?.[5]?.book?.title ?? "nessuna sesta riga");
// percorso da stringa, senza librerie: una funzione di 5 righefunction leggi(obj: unknown, percorso: string, fallback?: unknown) { return percorso.split(".").reduce<any>((acc, k) => (acc == null ? undefined : acc[k]), obj) ?? fallback;}console.log(leggi(o, "shipping_address.zip")); // 15399console.log(leggi(o, "items.0.book.price")); // 12.04console.log(leggi(o, "items.9.book.price", 0)); // 0
// "jq in TypeScript": map/filter/sort sui daticonst lista = await (await fetch(`${BASE}/books?limit=100`)).json();const top3 = [...lista.items].sort((a, b) => b.price - a.price).slice(0, 3).map((b) => `${b.price}\t${b.title}`);console.log(top3.join("\n"));Cosa dovresti vedere:
Pietro GalliBarin/dnessuna sesta riga1539912.04034.49 Quello che resta di Sestri34.36 Ustica e il Novecento33.49 La cucina di UsticaPer JSONPath vero in TS esiste jsonpath-plus (npm install jsonpath-plus): JSONPath({ path: "$.items[*].book.title", json: o }).
Prova subito
Sezione intitolata “Prova subito”Header della risposta
Header della risposta
Esercizio
Sezione intitolata “Esercizio”Provalo online, senza installare nulla:
La richiesta GET diretta nel browser: https://corso-api-json.giuseppebosi.com/api/v1/orders/1?expand=items.book,customer
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 jq (o in Python/TS) partendo da /api/v1/categories?tree=true:
- Stampa i nomi delle sole categorie radice.
- Stampa, per ogni radice, i nomi delle sottocategorie.
- Somma
books_countdi tutte le categorie, a qualsiasi livello (suggerimento jq:..visita ricorsivamente tutti i nodi).
Soluzione
URL='https://corso-api-json.giuseppebosi.com/api/v1/categories?tree=true'curl -s "$URL" | jq -r '.items[].name' # 1curl -s "$URL" | jq -r '.items[] | "\(.name): \([.children[].name] | join(", "))"' # 2curl -s "$URL" | jq '[.. | .books_count? | numbers] | add' # 3 → 80.. produce ogni valore dell’albero; .books_count? prova a leggere la chiave ignorando gli errori sui non-oggetti; numbers scarta i null.
Errori comuni
Sezione intitolata “Errori comuni”o["items"][0]su una lista vuota →IndexError/undefined: controlla la lunghezza o usa?.[0].- Confondere
nullcon “chiave assente”: in jq e in JS entrambi arrivano comenull/undefined; se la differenza conta, usahas("k")(jq) /"k" in obj(JS) /"k" in d(Python). - Dimenticare gli apici intorno all’URL con
?e&: la shell spezza il comando in silenzio. jq '.items[].price | add'non funziona:addvuole un array, quindi[.items[].price] | addoppure.items | map(.price) | add.
In sintesi
Sezione intitolata “In sintesi”Accesso diretto quando la forma è garantita, accesso sicuro (.get, ?.) quando può mancare qualcosa, jq/JSONPath per esplorare. E ricorda: l’annidamento nasce dalle relazioni tra tabelle, che l’API espande per te. Prossimo capitolo: quando il JSON è troppo grande per stare in memoria.