Salta ai contenuti

Tutti gli endpoint

Base URL: https://corso-api-json.giuseppebosi.com/api/v1. Documentazione interattiva generata da OpenAPI: Swagger UI; lo schema è scaricabile da /api/openapi.json.

Sandbox: gli endpoint marcati ✍️ richiedono Authorization: Bearer <token> (token da POST /sandbox). Gli altri funzionano anche senza token, sul dataset pubblico; con il token leggono la tua copia.

Limite: 30 richieste al minuto per IP sul server pubblico (120 in locale) → 429 con Retry-After. Errori: sempre {"error": {"code", "message", "details"?}}.

Metodo Percorso Cosa fa Cap.
GET / indice con i link principali 1
GET /health stato del servizio 1
GET, POST, PUT /echo rimanda metodo, query, header e body ricevuti 2
GET /schema tabelle, colonne, chiavi primarie ed esterne, conteggi 5, 12
Metodo Percorso Cosa fa Cap.
POST /sandbox crea una copia privata del database → {token, expires_at} (201) 6
GET /sandbox ✍️ informazioni sulla sandbox del token 6
POST /sandbox/reset ✍️ riporta la sandbox ai dati iniziali 6
DELETE /sandbox ✍️ elimina la sandbox (204) 6
GET /sandbox/me 200 con token valido, 401 senza 8
Metodo Percorso Cosa fa Cap.
GET /books elenco con filtri (q, author_id, category, tag, min_price, max_price, year_from, year_to, language, in_stock, format), sort (id, title, price, year, pages, created_at, rating; - = desc), page/limit (max 100), expand=author,category,tags 3, 4
GET /books/{id} dettaglio con ETag; expand=author,category,tags,reviews 3, 5, 14
POST /books ✍️ crea (201 + Location) 6
PUT /books/{id} ✍️ sostituisce per intero 6
PATCH /books/{id} ✍️ modifica i campi inviati 6
DELETE /books/{id} ✍️ elimina (204); 409 book_in_orders se presente in ordini 6, 13
GET /books/{id}/reviews recensioni con nome e città del cliente (JOIN); min_rating 5
POST /books/{id}/reviews ✍️ aggiunge una recensione 6
DELETE /reviews/{id} ✍️ elimina una recensione 6
GET /export/books.csv, /export/books.ndjson export in streaming JSON 11
Metodo Percorso Cosa fa Cap.
GET /authors elenco con books_count; filtro country 5
GET /authors/{id} un autore 5
GET /authors/{id}/books i suoi libri (risorsa annidata) 5
GET /categories piatte; ?tree=true ad albero (children) 5
GET /categories/{slug}/books libri della categoria e delle sottocategorie (deep=false per la sola categoria) 5
GET /customers elenco; filtro city 5
GET /customers/{id} cliente con orders_summary 5
POST /customers ✍️ crea; 409 duplicate_email 13
GET /customers/{id}/orders ordini del cliente 5
GET /orders elenco; status, customer_id, from, to, sort 4
GET /orders/{id} un ordine; expand=items,items.book,customer (default items) 5
POST /orders ✍️ crea ordine + righe in transazione; 422 unknown_book, 409 out_of_stock 13
PATCH /orders/{id} ✍️ cambia stato; 409 invalid_transition con allowed 13
DELETE /orders/{id} ✍️ elimina ordine e righe (cascade) 13
Metodo Percorso Cosa fa Cap.
GET /search?q= full-text FTS5 con ranking (score) e snippet; limit ≤ 50 9
GET /stats totali, prezzi, libri per categoria, top autori, ordini per stato 10
GET /stats/sales group_by = month, category, author, city, from, to 10
POST /query filtro strutturato JSON → SQL parametrico; risposta con meta.sql 11
POST /sql SELECT in sola lettura (authorizer), max 200 righe, 2 s; params, explain 12
Header Dove Significato
X-Request-Id tutte identificativo della richiesta, da citare nei log
ETag, Cache-Control GET /books/{id} (e Cache-Control: no-store con token) cache condizionale (cap. 14)
Location 201 di POST /books, POST /orders URL della risorsa creata
Retry-After 429 secondi da attendere
Access-Control-* tutte CORS aperto (cap. 15)
Content-Encoding risposte compresse gzip dall’API, o zstd da Caddy in produzione (cap. 14)
Strict-Transport-Security, X-Frame-Options, … solo in produzione aggiunti dal reverse proxy (Caddy)