Salta ai contenuti

1. Cos'è JSON

  • Sapere cos’è JSON e perché è diventato il formato di scambio universale.
  • Riconoscere a colpo d’occhio le parti di un documento JSON: oggetti, array, valori.
  • Leggere un JSON reale restituito da un’API e capire “cosa c’è dentro”.

JSON (JavaScript Object Notation) è un formato di testo per rappresentare dati strutturati. Nasce nel 2001 da Douglas Crockford come sottoinsieme della sintassi degli oggetti JavaScript, ed è standardizzato in RFC 8259 ed ECMA-404. Tre proprietà lo hanno reso onnipresente:

  1. È testo (UTF-8): lo leggi in un editor, lo mandi in una richiesta HTTP, lo salvi in un file, lo metti in una colonna di database.
  2. È indipendente dal linguaggio: ogni linguaggio ha una libreria per trasformare i propri oggetti in JSON (serializzare) e viceversa (deserializzare o parsare).
  3. È semplice: sei tipi di valore e due strutture. Tutto qui.

Un documento JSON è composto da:

Elemento Aspetto Esempio
Oggetto coppie "chiave": valore tra graffe {"id": 1, "title": "Oltre Trieste"}
Array lista ordinata tra quadre ["novità", "premio"]
Stringa testo tra doppi apici "Elena Marchetti"
Numero intero o decimale, notazione scientifica ammessa 18.71, 2002, 1e3
Booleano true o false true
null assenza di valore null

Oggetti e array si annidano senza limiti: un oggetto può contenere array di oggetti che contengono oggetti… È così che JSON rappresenta strutture complesse come un ordine con le sue righe, o un libro con il suo autore.

  • API HTTP: quasi ogni servizio web risponde in JSON (Content-Type: application/json).
  • File di configurazione: package.json, tsconfig.json, settings.json di VS Code.
  • Database: PostgreSQL (jsonb), SQLite (funzioni json_*), MongoDB (documenti BSON, un JSON binario).
  • Log e dati: una riga JSON per evento (JSON Lines, lo vedremo nel capitolo 11).

Chiediamo al server di prova il libro con id 1. Prima con curl, spiegato opzione per opzione:

terminale
curl -s https://corso-api-json.giuseppebosi.com/api/v1/books/1
curl
esegue una richiesta HTTP e stampa la risposta sul terminale
-s
silent: nasconde la barra di avanzamento, così vedi solo la risposta
https://corso-api-json.giuseppebosi.com
schema (https) e host del server
/api/v1/books/1
il percorso: risorsa books, elemento con id 1. Nessun metodo indicato = GET

Risposta (riformattata con gli a capo per leggerla; sul filo viaggia su una riga sola):

{
"id": 1,
"title": "Il silenzio di Ustica",
"isbn": "978-88-81482-001-1",
"author_id": 19,
"category_id": 2,
"price": 18.71,
"pages": 120,
"published_year": 2002,
"language": "it",
"in_stock": true,
"attributes": {
"format": "brossura",
"cover": "morbida",
"awards": [],
"dimensions_cm": { "w": 15, "h": 19 },
"ebook": false
},
"created_at": "2025-06-01T00:00:00Z",
"reviews_count": 0,
"avg_rating": null
}

Leggiamolo con la regola mentale:

  • La graffa iniziale: è un oggetto, il libro.
  • "id": 1 → numero. "title": "…" → stringa. "in_stock": true → booleano. "avg_rating": null → nessun valore (il libro non ha ancora recensioni).
  • "attributes": { … } → un oggetto dentro l’oggetto: contiene a sua volta "awards": [] (un array vuoto) e "dimensions_cm": {"w": 15, "h": 19} (un altro oggetto).
  • "created_at": "2025-06-01T00:00:00Z" → attenzione: è una stringa. JSON non ha un tipo “data”: ci torneremo nel capitolo 3.
  • "author_id": 19 → un numero che rimanda a un’altra risorsa (l’autore 19). È il modo in cui JSON, e i database, esprimono le relazioni: lo approfondirai nella Sezione 2.

Ora eseguilo tu, dal browser:

GET/api/v1/books/1— il libro con id 1

Nei prossimi capitoli entreremo nel dettaglio; intanto ecco quanto poco serve per scaricare quel JSON e trasformarlo in un oggetto del linguaggio.

# pip install httpx
import httpx
r = httpx.get("https://corso-api-json.giuseppebosi.com/api/v1/books/1")
libro = r.json() # da testo JSON a dict Python
print(type(libro)) # <class 'dict'>
print(libro["title"]) # Il silenzio di Ustica
print(libro["attributes"]["dimensions_cm"]["h"]) # 19

Cosa dovresti vedere:

<class 'dict'>
Il silenzio di Ustica
19

Provalo online, senza installare nulla:

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

La richiesta GET diretta nel browser: https://corso-api-json.giuseppebosi.com/api/v1/books/1

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/.

Scarica https://corso-api-json.giuseppebosi.com/api/v1/orders/1 (con curl o col pulsante qui sotto) e rispondi:

  1. Quanti livelli di annidamento ha shipping_address?
  2. items è un oggetto o un array? Quanti elementi ha?
  3. Quale campo lega ogni riga dell’ordine a un libro?
GET/api/v1/orders/1— l'ordine 1 con le sue righe
Soluzione
  1. Uno: shipping_address è un oggetto con quattro stringhe (street, city, zip, country).
  2. Un array ([…]) di oggetti: una riga per ogni libro ordinato (il numero dipende dall’ordine: nell’ordine 1 è 1).
  3. book_id: è una chiave esterna verso books.id. Nella Sezione 2, capitolo 5, imparerai a “seguirla” con ?expand=items.book.
  • Confondere JSON con un oggetto JavaScript. JSON è testo; l’oggetto è ciò che ottieni dopo il parsing. '{"a":1}' (stringa) ≠ {a: 1} (oggetto).
  • Apici singoli. {'a': 1} non è JSON valido: le stringhe e le chiavi vanno tra doppi apici.
  • Virgola finale. {"a": 1,} non è valido. Molti editor la tollerano, i parser no.

JSON è testo, con sei tipi e due strutture annidabili. Un’API lo restituisce, il tuo linguaggio lo trasforma in oggetti nativi, e viceversa. Nel prossimo capitolo la sintassi completa, regola per regola.