4. Filtri, ordinamento, paginazione
Obiettivi
Sezione intitolata “Obiettivi”- Combinare più filtri nella query string e sapere quali valori accetta ciascuno.
- Ordinare con
sort=campo/sort=-campo. - Capire la paginazione a offset (
page/limit) e i suoi limiti; leggeremetaelinks. - Scrivere un ciclo che scarica tutte le pagine seguendo
links.next, in Python e TypeScript. - Riconoscere gli errori di parametri (400, 422) prima che diventino bug.
Filtrare
Sezione intitolata “Filtrare”Una collezione può avere migliaia di elementi: il client dice quali vuole con parametri di query. Su /api/v1/books sono disponibili:
| Parametro | Cosa fa | Esempio |
|---|---|---|
q |
testo contenuto nel titolo (LIKE %q%, senza distinzione maiuscole) |
q=trieste |
author_id |
libri di un autore (chiave esterna) | author_id=4 |
category |
slug della categoria, incluse le sottocategorie | category=narrativa prende anche gialli, fantascienza, storici |
tag |
libri con quel tag (relazione N-N) | tag=premio |
min_price, max_price |
intervallo di prezzo (inclusivo) | min_price=10&max_price=20 |
year_from, year_to |
intervallo di anno di pubblicazione | year_from=2000 |
language |
codice lingua | language=en |
in_stock |
true/false |
in_stock=true |
format |
valore di attributes.format, una colonna JSON |
format=tascabile |
I filtri si sommano con AND: category=gialli&max_price=15 = gialli e sotto i 15 €. (Per OR e condizioni complesse c’è POST /query, capitolo 11.)
I valori arrivano al server come stringhe: è il server a convertirle (min_price=10 → numero) e a validarle. Se mandi min_price=dieci ottieni 422.
Ordinare
Sezione intitolata “Ordinare”sort=price crescente, sort=-price decrescente: il segno meno davanti al nome è una convenzione diffusa (JSON:API, molte API REST). Campi ammessi qui: id, title, price, year, pages, created_at, rating. A parità di valore il server ordina per id, così l’ordine è stabile tra una pagina e l’altra (senza questa regola, un elemento potrebbe comparire in due pagine o in nessuna).
Paginare
Sezione intitolata “Paginare”Con 80 libri ok, con 80.000 no: le risposte sono divise in pagine.
limit= elementi per pagina (qui default 20, massimo 100).page= quale pagina, da 1.- Il server calcola
OFFSET (page-1)*limitnella query SQL: è la paginazione a offset. Semplice, ma con offset enormi diventa lenta e, se nel frattempo qualcuno inserisce un elemento, le pagine “scivolano”. L’alternativa — la paginazione a cursore (?after=<id>) — è accennata nel capitolo 14.
La risposta ti dice dove sei e come continuare:
"meta": { "page": 1, "limit": 3, "total": 4, "pages": 2 },"links": { "self": "…page=1…", "next": "…page=2…", "prev": null }links.next è null sull’ultima pagina: è la condizione di uscita del ciclo. E contiene già tutti i filtri: il client non deve ricostruire nulla.
curl, spiegato
Sezione intitolata “curl, spiegato”I gialli più cari, tre per pagina:
curl -sS -G https://corso-api-json.giuseppebosi.com/api/v1/books \--data-urlencode 'category=gialli' \--data-urlencode 'sort=-price' \--data-urlencode 'limit=3' | jq '{meta, links, titoli: [.items[] | "\(.id) \(.title) \(.price)"]}'- -G
- manda i
--data-urlencodenella query string (metodo GET) - category=gialli
- filtro sulla categoria (slug), ricorsivo sulle sottocategorie
- sort=-price
- prezzo decrescente
- limit=3
- tre per pagina;
pagenon indicato = 1 - | jq …
- costruisce un oggetto con
meta,linkse una lista di stringhe"id titolo prezzo"(in jq\(…)interpola dentro le stringhe)
{ "meta": { "page": 1, "limit": 3, "total": 4, "pages": 2 }, "links": { "self": "https://corso-api-json.giuseppebosi.com/api/v1/books?category=gialli&sort=-price&page=1&limit=3", "next": "https://corso-api-json.giuseppebosi.com/api/v1/books?category=gialli&sort=-price&page=2&limit=3", "prev": null }, "titoli": [ "48 La casa sul Porto Vecchio 21.77", "1 Il silenzio di Ustica 18.71", "67 Nebbia su Lecce 11.18" ]}Quattro gialli in tutto, due pagine: la seconda si prende con --data-urlencode 'page=2' oppure semplicemente con curl -sS "$(…links.next…)".
Un filtro su una colonna JSON combinato con altri:
curl -sS 'https://corso-api-json.giuseppebosi.com/api/v1/books?format=tascabile&in_stock=true&min_price=10&max_price=20&limit=2' \| jq '.meta.total, (.items[] | [.id, .title, .price, .attributes.format])'- '…?format=…&in_stock=…'
- qui la query string è scritta a mano: nessun valore ha spazi o caratteri speciali, ma l'URL va comunque tra apici per via di
& - format=tascabile
- filtra
attributes.format: il server usajson_extract(attributes, '$.format')in SQL - in_stock=true
- booleano: accettati
true/false,1/0 - | jq …
- stampa il totale e, per ogni libro, un array con quattro campi
11[14,"Le avventure di Orvieto",10.56,"tascabile"][21,"Il drago di Alba",18.98,"tascabile"]E gli errori di parametri:
curl -sS 'https://corso-api-json.giuseppebosi.com/api/v1/books?sort=boh'curl -sS 'https://corso-api-json.giuseppebosi.com/api/v1/books?limit=500'- sort=boh
- campo di ordinamento inesistente →
400 bad_sort, e indetails.allowedl'elenco di quelli validi - limit=500
- oltre il massimo →
422 validation_error, condetails[].locche indica["query","limit"]
{"error":{"code":"bad_sort","message":"sort non valido: boh","details":{"allowed":["created_at","id","pages","price","rating","title","year"]}}}{"error":{"code":"validation_error","message":"Richiesta non valida: controlla i campi in details","details":[{"loc":["query","limit"],"msg":"Input should be less than or equal to 100","type":"less_than_equal"}]}}Python e TypeScript: scaricare tutte le pagine
Sezione intitolata “Python e TypeScript: scaricare tutte le pagine”Il pattern è sempre lo stesso: parti dall’URL con i filtri, poi segui links.next finché non è null. Attenzione a un dettaglio: i parametri vanno passati solo alla prima richiesta, perché next li contiene già.
# python3 tutte_le_pagine.pyimport httpx
url = "https://corso-api-json.giuseppebosi.com/api/v1/books"params = {"category": "saggistica", "sort": "-price", "limit": 10}tutti = []with httpx.Client() as client: # un Client riusa la connessione tra le richieste while url: r = client.get(url, params=params) r.raise_for_status() dati = r.json() tutti.extend(dati["items"]) print(f'pagina {dati["meta"]["page"]}/{dati["meta"]["pages"]}: {len(dati["items"])} libri') url, params = dati["links"]["next"], None # next contiene già filtri e limitprint(len(tutti), "libri in totale; il più caro:", tutti[0]["title"], tutti[0]["price"])Cosa dovresti vedere:
pagina 1/4: 10 libripagina 2/4: 10 libripagina 3/4: 10 libripagina 4/4: 4 libri34 libri in totale; il più caro: Ustica e il Novecento 34.36// node --experimental-strip-types tutte_le_pagine.tslet url: string | null = "https://corso-api-json.giuseppebosi.com/api/v1/books?category=saggistica&sort=-price&limit=10";const tutti: { title: string; price: number }[] = [];while (url) { const r = await fetch(url); if (!r.ok) throw new Error("HTTP " + r.status); const dati = await r.json(); tutti.push(...dati.items); console.log(`pagina ${dati.meta.page}/${dati.meta.pages}: ${dati.items.length} libri`); url = dati.links.next; // null sull'ultima pagina → esce dal while}console.log(tutti.length, "libri in totale; il più caro:", tutti[0].title, tutti[0].price);Output (identico nei due linguaggi):
pagina 1/4: 10 libripagina 2/4: 10 libripagina 3/4: 10 libripagina 4/4: 4 libri34 libri in totale; il più caro: Ustica e il Novecento 34.36Prova subito
Sezione intitolata “Prova subito”Header della risposta
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/books?category=narrativa&year_from=2015&sort=year&limit=5
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/.
- Quanti libri in inglese ci sono in catalogo, e qual è il più economico? (Un solo comando curl, con
jqopython3 -m json.tool.) - Scrivi una funzione
tutti(url, params)che restituisca la lista completa degli elementi di qualunque collezione, e usala per contare gli ordini constatus=delivered(endpoint/api/v1/orders, stessimeta/links).
Soluzione
-
curl -sS 'https://corso-api-json.giuseppebosi.com/api/v1/books?language=en&sort=price&limit=1' | jq '.meta.total, .items[0].title, .items[0].price'
import httpxdef tutti(url, params=None): out = [] with httpx.Client() as c: while url: d = c.get(url, params=params).raise_for_status().json() out += d["items"] url, params = d["links"]["next"], None return outconsegnati = tutti("https://corso-api-json.giuseppebosi.com/api/v1/orders", {"status": "delivered", "limit": 100})print(len(consegnati))Cosa dovresti vedere:
48async function tutti(url: string | null) { const out: any[] = []; while (url) { const r = await fetch(url); if (!r.ok) throw new Error("HTTP " + r.status); const d = await r.json(); out.push(...d.items); url = d.links.next; } return out;}const consegnati = await tutti("https://corso-api-json.giuseppebosi.com/api/v1/orders?status=delivered&limit=100");console.log(consegnati.length);Cosa dovresti vedere:
48Errori comuni
Sezione intitolata “Errori comuni”- Ripassare
paramsa ogni pagina insieme alinks.next: i parametri vengono duplicati o sovrascritti (page=2ripetuto). Passa i parametri solo la prima volta. - Contare
len(items)invece di leggeremeta.total:itemsè solo la pagina corrente. - Ignorare
meta.pagese fare unfor page in range(1, 1000): chiedi pagine vuote e bruci il rate limit. Usalinks.next. sort=price desc: la sintassi è-price. Lo spazio, tra l’altro, va codificato.- Ordinare lato client dopo aver scaricato solo una pagina: ordini 20 elementi su 80.
In sintesi
Sezione intitolata “In sintesi”Filtri in AND nella query string (anche su relazioni e colonne JSON), sort=-campo, page/limit con massimo 100, e links.next per scorrere tutto. Nel prossimo capitolo seguiamo le chiavi esterne: da un ordine ai suoi libri, ai loro autori, in una richiesta sola.