17. Progetto finale
Obiettivi
Sezione intitolata “Obiettivi”Mettere insieme tutto quello che hai imparato nella Sezione 2 in un solo programma, in Python o in TypeScript, che:
- crea una sandbox e usa il token per tutte le chiamate;
- legge
GET /schemaper conoscere tabelle, chiavi primarie ed esterne, e scarica catalogo e autori pagina per pagina; - ricostruisce le tabelle in un SQLite locale con le stesse chiavi (
books.author_id → authors.id); - crea un cliente e un ordine con più righe (transazione), poi lo porta a
paid; - produce un report con un
GROUP BYlocale e lo confronta conGET /statsdel server: devono coincidere.
Teoria: sincronizzare, non copiare a mano
Sezione intitolata “Teoria: sincronizzare, non copiare a mano”Molte applicazioni reali fanno esattamente questo: leggono da un’API e tengono una copia locale interrogabile (cache, reportistica, app offline). I punti di attenzione:
- Paginazione completa: segui
links.nextfinché ènull; fermarsi alla prima pagina è l’errore più comune. - Stesse chiavi: conserva gli
idremoti come chiavi primarie locali, così le FK restano valide e i JOIN locali funzionano. - Espansione mirata:
?expand=categoryti dà loslugdella categoria in una sola chiamata, invece di 80 chiamate a/categories. - Idempotenza della sincronizzazione: rilanciare lo script non deve duplicare (qui:
DROP TABLE IF EXISTSe ricreazione; in produzioneINSERT … ON CONFLICT DO UPDATE). - Verifica: un numero calcolato in locale confrontato con lo stesso numero calcolato dal server è il test più semplice ed efficace.
curl, spiegato opzione per opzione
Sezione intitolata “curl, spiegato opzione per opzione”Prima di scrivere codice, la sequenza a mano, per vedere ogni passo:
BASE=https://corso-api-json.giuseppebosi.com/api/v1TOKEN=$(curl -s -X POST $BASE/sandbox | python3 -c 'import sys, json; print(json.load(sys.stdin)["token"])')AUTH="Authorization: Bearer $TOKEN"
# 1. lo schema: quali tabelle, quante righe, quali chiavicurl -s $BASE/schema -H "$AUTH" | python3 -c 'import sys, jsonfor nome, t in json.load(sys.stdin)["tables"].items(): fk = ", ".join(c["column"] + "→" + c["references"]["table"] for c in t["foreign_keys"]) print("%-12s %4d righe PK %s FK %s" % (nome, t["rows"], t["primary_key"], fk))'
# 2. tutte le pagine del catalogo, con la categoria espansafor page in 1 2; docurl -s "$BASE/books?expand=category&limit=50&page=$page" -H "$AUTH" | python3 -c 'import sys, jsond = json.load(sys.stdin); print("pagina %d/%d: %d libri, next=%s" % (d["meta"]["page"], d["meta"]["pages"], len(d["items"]), d["links"]["next"]))'done- BASE=… / AUTH=…
- variabili di shell per non ripetere URL e header;
$BASEe"$AUTH"vengono sostituiti - # …
- commenti della shell: ignorati
- python3 -c '…' su più righe
- un piccolo programma Python passato come stringa: legge il JSON e stampa una riga per tabella
- "%-12s %4d" % (…)
- formattazione con
%, valida in ogni versione di Python 3:%-12s= testo largo 12, allineato a sinistra;%4d= intero largo 4 - for page in 1 2
- due pagine da 50 coprono gli 80 libri; nello script vero il ciclo si ferma quando
links.nextènull
authors 20 righe PK ['id'] FKbook_tags 126 righe PK ['book_id', 'tag_id'] FK tag_id→tags, book_id→booksbooks 80 righe PK ['id'] FK category_id→categories, author_id→authorscategories 10 righe PK ['id'] FK parent_id→categoriescustomers 40 righe PK ['id'] FKorder_items 305 righe PK ['id'] FK book_id→books, order_id→ordersorders 120 righe PK ['id'] FK customer_id→customersreviews 243 righe PK ['id'] FK customer_id→customers, book_id→bookstags 10 righe PK ['id'] FKpagina 1/2: 50 libri, next=https://…/books?expand=category&limit=50&page=2pagina 2/2: 30 libri, next=NonePoi cliente, ordine, pagamento e confronto — esattamente ciò che lo script automatizza:
curl -s -X POST $BASE/customers -H "$AUTH" -H 'Content-Type: application/json' \ -d '{"name": "Mario Verdi", "email": "mario.verdi@example.com", "city": "Bologna"}'# → {"id":41,"name":"Mario Verdi",…}curl -s -X POST $BASE/orders -H "$AUTH" -H 'Content-Type: application/json' \ -d '{"customer_id": 41, "items": [{"book_id": 12, "quantity": 1}, {"book_id": 3, "quantity": 2}], "shipping_address": {"street": "Via Zamboni 7", "city": "Bologna", "zip": "40126"}}'# → {"id":121,"status":"pending","total":96.81,"items":[…]}curl -s -X PATCH $BASE/orders/121 -H "$AUTH" -H 'Content-Type: application/json' -d '{"status": "paid"}'# → {"id":121,"status":"paid",…}curl -s $BASE/stats | python3 -c 'import sys, json; [print(c) for c in json.load(sys.stdin)["books_by_category"]]'curl -s -X DELETE $BASE/sandbox -H "$AUTH" # pulizia: 204Python e TypeScript: il programma completo
Sezione intitolata “Python e TypeScript: il programma completo”Lo stesso programma nei due linguaggi; l’output è riportato dopo il codice.
# pip install httpx → python3 progetto.py"""Progetto finale: sincronizza il catalogo in un SQLite locale, crea un ordine in sandbox,produce un report con JOIN locali e lo confronta con /stats."""import sqlite3
import httpx
BASE = "https://corso-api-json.giuseppebosi.com/api/v1"
# (a) sandboxtoken = httpx.post(f"{BASE}/sandbox").json()["token"]api = httpx.Client(base_url=BASE, headers={"Authorization": f"Bearer {token}"}, timeout=15)
# (b) schema e catalogoschema = api.get("/schema").json()["tables"]print("tabelle remote:", ", ".join(f"{t} ({v['rows']})" for t, v in schema.items()))
def tutte(path, **params): """Generatore: scorre tutte le pagine finché links.next è null.""" page = 1 while True: d = api.get(path, params={**params, "page": page, "limit": 100}).json() yield from d["items"] if not d["links"]["next"]: return page += 1
# (c) SQLite locale con le stesse chiavidb = sqlite3.connect("libreria_locale.db")db.executescript("""DROP TABLE IF EXISTS books; DROP TABLE IF EXISTS authors;CREATE TABLE authors (id INTEGER PRIMARY KEY, name TEXT, country TEXT);CREATE TABLE books (id INTEGER PRIMARY KEY, title TEXT, price REAL, category TEXT, author_id INTEGER REFERENCES authors(id));""")db.executemany("INSERT INTO authors VALUES (?,?,?)", [(a["id"], a["name"], a["country"]) for a in tutte("/authors")])db.executemany("INSERT INTO books VALUES (?,?,?,?,?)", [(b["id"], b["title"], b["price"], b["category"]["slug"], b["author_id"]) for b in tutte("/books", expand="category")])print("libri locali:", db.execute("SELECT COUNT(*) FROM books").fetchone()[0])
# (d) un cliente e un ordine, poi pagamentocliente = api.post("/customers", json={"name": "Mario Verdi", "email": "mario.verdi@example.com", "city": "Bologna"}).json()ordine = api.post("/orders", json={"customer_id": cliente["id"], "items": [{"book_id": 12, "quantity": 1}, {"book_id": 3, "quantity": 2}], "shipping_address": {"street": "Via Zamboni 7", "city": "Bologna", "zip": "40126"}}).json()ordine = api.patch(f"/orders/{ordine['id']}", json={"status": "paid"}).json()print(f"ordine {ordine['id']}: {ordine['status']}, totale {ordine['total']} €")
# (e) report: JOIN locale vs aggregazione remotaprint("\nLibri e prezzo medio per categoria (JOIN locale):")locale = {r[0]: (r[1], r[2]) for r in db.execute( "SELECT category, COUNT(*), ROUND(AVG(price),2) FROM books GROUP BY category ORDER BY 2 DESC")}remoto = {r["slug"]: (r["books"], r["avg_price"]) for r in api.get("/stats").json()["books_by_category"]}for cat, (n, media) in locale.items(): print(f" {cat:<13} {n:>2} libri media {media:>6.2f} € remoto: {remoto[cat]} {'OK' if remoto[cat] == (n, media) else 'DIVERSO'}")api.delete("/sandbox")Cosa dovresti vedere:
tabelle remote: authors (20), book_tags (126), books (80), categories (10), customers (40), order_items (305), orders (120), reviews (243), tags (10)libri locali: 80ordine 121: paid, totale 96.81 €
Libri e prezzo medio per categoria (JOIN locale): saggistica 14 libri media 17.04 € remoto: (14, 17.04) OK ragazzi 12 libri media 16.72 € remoto: (12, 16.72) OK cucina 9 libri media 18.39 € remoto: (9, 18.39) OK narrativa 8 libri media 22.78 € remoto: (8, 22.78) OK storici 7 libri media 19.96 € remoto: (7, 19.96) OK storia 7 libri media 24.31 € remoto: (7, 24.31) OK informatica 7 libri media 19.11 € remoto: (7, 19.11) OK scienza 6 libri media 22.11 € remoto: (6, 22.11) OK fantascienza 6 libri media 27.67 € remoto: (6, 27.67) OK gialli 4 libri media 15.70 € remoto: (4, 15.7) OK// node --experimental-strip-types --experimental-sqlite progetto.ts (Node 22.5+; package.json con "type": "module")import { DatabaseSync } from "node:sqlite";
const BASE = "https://corso-api-json.giuseppebosi.com/api/v1";
// (a) sandboxconst { token } = await (await fetch(`${BASE}/sandbox`, { method: "POST" })).json();const api = async (method: string, path: string, body?: unknown) => { const r = await fetch(BASE + path, { method, headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" }, body: body === undefined ? undefined : JSON.stringify(body) }); if (!r.ok && r.status !== 204) throw new Error(`${method} ${path}: ${r.status} ${await r.text()}`); return r.status === 204 ? null : r.json();};
// (b) schema e catalogoconst schema = (await api("GET", "/schema")).tables;console.log("tabelle remote:", Object.entries(schema).map(([t, v]: any) => `${t} (${v.rows})`).join(", "));async function tutte(path: string, params: Record<string, string> = {}) { const out: any[] = []; for (let page = 1; ; page++) { // finché links.next è null const d = await api("GET", `${path}?${new URLSearchParams({ ...params, page: String(page), limit: "100" })}`); out.push(...d.items); if (!d.links.next) return out; }}
// (c) SQLite locale con le stesse chiaviconst db = new DatabaseSync("libreria_locale.db");db.exec(`DROP TABLE IF EXISTS books; DROP TABLE IF EXISTS authors; CREATE TABLE authors (id INTEGER PRIMARY KEY, name TEXT, country TEXT); CREATE TABLE books (id INTEGER PRIMARY KEY, title TEXT, price REAL, category TEXT, author_id INTEGER REFERENCES authors(id));`);const insA = db.prepare("INSERT INTO authors VALUES (?,?,?)");for (const a of await tutte("/authors")) insA.run(a.id, a.name, a.country);const insB = db.prepare("INSERT INTO books VALUES (?,?,?,?,?)");for (const b of await tutte("/books", { expand: "category" })) insB.run(b.id, b.title, b.price, b.category.slug, b.author_id);console.log("libri locali:", (db.prepare("SELECT COUNT(*) AS n FROM books").get() as any).n);
// (d) un cliente e un ordine, poi pagamentoconst cliente = await api("POST", "/customers", { name: "Mario Verdi", email: "mario.verdi@example.com", city: "Bologna" });let ordine = await api("POST", "/orders", { customer_id: cliente.id, items: [{ book_id: 12, quantity: 1 }, { book_id: 3, quantity: 2 }], shipping_address: { street: "Via Zamboni 7", city: "Bologna", zip: "40126" } });ordine = await api("PATCH", `/orders/${ordine.id}`, { status: "paid" });console.log(`ordine ${ordine.id}: ${ordine.status}, totale ${ordine.total} €`);
// (e) report: JOIN locale vs aggregazione remotaconsole.log("\nLibri e prezzo medio per categoria (JOIN locale):");const remoto = new Map<string, [number, number]>((await api("GET", "/stats")).books_by_category.map((r: any) => [r.slug, [r.books, r.avg_price]]));for (const r of db.prepare("SELECT category, COUNT(*) AS n, ROUND(AVG(price),2) AS media FROM books GROUP BY category ORDER BY n DESC").all() as any[]) { const [n, media] = remoto.get(r.category)!; console.log(` ${r.category.padEnd(13)} ${String(r.n).padStart(2)} libri media ${r.media.toFixed(2).padStart(6)} € remoto: (${n}, ${media}) ${n === r.n && media === r.media ? "OK" : "DIVERSO"}`);}await api("DELETE", "/sandbox");Cosa dovresti vedere:
tabelle remote: authors (20), book_tags (126), books (80), categories (10), customers (40), order_items (305), orders (120), reviews (243), tags (10)libri locali: 80ordine 121: paid, totale 96.81 €
Libri e prezzo medio per categoria (JOIN locale): saggistica 14 libri media 17.04 € remoto: (14, 17.04) OK ragazzi 12 libri media 16.72 € remoto: (12, 16.72) OK cucina 9 libri media 18.39 € remoto: (9, 18.39) OK narrativa 8 libri media 22.78 € remoto: (8, 22.78) OK storici 7 libri media 19.96 € remoto: (7, 19.96) OK storia 7 libri media 24.31 € remoto: (7, 24.31) OK informatica 7 libri media 19.11 € remoto: (7, 19.11) OK scienza 6 libri media 22.11 € remoto: (6, 22.11) OK fantascienza 6 libri media 27.67 € remoto: (6, 27.67) OK gialli 4 libri media 15.70 € remoto: (4, 15.7) OKDieci OK: il tuo database locale e il server raccontano la stessa storia.
Prova subito
Sezione intitolata “Prova subito”I pezzi del progetto, uno per uno:
Header della risposta
Header della risposta
Header della risposta
Header della risposta
Header della risposta
Header della risposta
Estensioni (scegline una)
Sezione intitolata “Estensioni (scegline una)”Provalo online, senza installare nulla:
La richiesta GET diretta nel browser: https://corso-api-json.giuseppebosi.com/api/v1/schema
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/.
- Sincronizzazione incrementale: aggiungi
orderseorder_itemsal database locale e, con unJOINlocale a quattro tabelle, riproduciGET /stats/sales?group_by=city. Confronta. - Robustezza: sostituisci le chiamate dirette con la
LibreriaClientdel capitolo 16 (timeout, retry, tipi). - Cache: conserva gli
ETagdi/books/{id}e, a una seconda esecuzione, riscarica solo i libri cambiati (capitolo 14). - CLI: trasforma lo script in un comando con argomenti (
--citta Bologna --libri 12,3) usandoargparseonode:util.parseArgs.
Traccia per l’estensione 1
Tabelle locali customers(id, name, city), orders(id, customer_id, status, created_at), order_items(order_id, book_id, quantity, unit_price). Poi:
SELECT cu.city, COUNT(DISTINCT o.id) AS orders, SUM(oi.quantity) AS books_sold, ROUND(SUM(oi.quantity * oi.unit_price), 2) AS revenueFROM orders o JOIN customers cu ON cu.id = o.customer_idJOIN order_items oi ON oi.order_id = o.idWHERE o.status != 'cancelled' GROUP BY cu.city ORDER BY cu.cityRicorda che nella tua sandbox c’è anche l’ordine che hai creato: per confrontare con il dataset pubblico, chiama /stats/sales senza token.
Cosa sai fare adesso
Sezione intitolata “Cosa sai fare adesso”Hai attraversato la Sezione 2 da un GET con curl fino a un programma che dialoga con un’API su più tabelle legate da chiavi, gestisce transazioni, errori, cache e limiti, e verifica il proprio lavoro. Le stesse idee — risorse, query string, expand, sandbox, 409 e 422, ETag, Retry-After, JOIN e aggregazioni — le ritroverai identiche in ogni API seria che incontrerai: cambiano i nomi, non la sostanza.
Riferimenti utili per continuare: tutti gli endpoint, il dataset, cheatsheet curl, glossario.