6. Sandbox e scritture
Obiettivi
Sezione intitolata “Obiettivi”- Creare una sandbox (una copia privata del database) e usarne il token in ogni richiesta di scrittura.
- Fare
POST(creare),PUT(sostituire),PATCH(modificare in parte),DELETE(eliminare) e leggere le risposte:201+Location,200,204,409. - Capire la differenza tra PUT e PATCH sul campo.
- Azzerare o eliminare la sandbox.
Perché una sandbox
Sezione intitolata “Perché una sandbox”Un server pubblico su cui chiunque può scrivere diventerebbe un caos in un’ora. Questo server usa un compromesso didattico: il dataset pubblico è in sola lettura; chi vuole scrivere chiede un token con POST /api/v1/sandbox, e da quel momento ogni richiesta che porta quel token lavora su una copia del database tutta sua. Il token è un segreto: chi lo ha, vede e modifica la tua copia. Scade dopo 6 ore di inattività (ogni richiesta rinnova il timer).
Il token si manda nell’header Authorization: Bearer <token> (standard, RFC 6750) oppure X-Sandbox-Token: <token>. Senza token, una scrittura risponde 401 con il codice sandbox_required.
I quattro verbi di scrittura
Sezione intitolata “I quattro verbi di scrittura”| Verbo | Sull’URL | Corpo | Risposta tipica | Idempotente |
|---|---|---|---|---|
POST |
la collezione (/books) |
l’oggetto nuovo | 201 Created + header Location con l’URL del nuovo elemento + l’oggetto creato |
no |
PUT |
l’elemento (/books/81) |
l’oggetto completo | 200 + l’oggetto |
sì |
PATCH |
l’elemento | solo i campi da cambiare | 200 + l’oggetto |
in pratica sì |
DELETE |
l’elemento | nessuno | 204 No Content (corpo vuoto) |
sì |
PUT vs PATCH è la distinzione che più spesso sorprende: con PUT i campi che non mandi vengono azzerati (o messi al default), perché stai sostituendo l’intera rappresentazione. Con PATCH restano com’erano.
Le regole del server (validazione e integrità)
Sezione intitolata “Le regole del server (validazione e integrità)”Il server non accetta qualunque cosa: title non vuoto, price ≥ 0, author_id e category_id devono esistere (chiavi esterne), l’ISBN dev’essere unico. Le violazioni tornano come 422 (dati non validi), 409 (conflitto con lo stato attuale: ISBN duplicato, libro presente in ordini). Capitolo 7 e 13 per i dettagli.
La tua sandbox
Sezione intitolata “La tua sandbox”Il pannello qui sotto crea il token e lo salva nel browser: tutti i widget Prova con scritture lo useranno da soli. (Il token resta solo sul tuo browser, in localStorage.)
Nessuna sandbox attiva in questo browser.
curl, spiegato
Sezione intitolata “curl, spiegato”1. Creare la sandbox e salvare il token
Sezione intitolata “1. Creare la sandbox e salvare il token”curl -sS -i -X POST https://corso-api-json.giuseppebosi.com/api/v1/sandbox- -i
- mostra gli header: vogliamo vedere lo status
201 - -X POST
- creare una sandbox è un'azione, quindi POST; nessun corpo richiesto
HTTP/1.1 201 Createdcontent-type: application/jsoncache-control: no-store
{"token":"sb_7cyEmMkco216unjxIBct6XTQ","created_at":"2026-09-18T20:03:39Z","expires_at":"2026-09-19T02:03:39Z","how_to_use":{"header":"Authorization: Bearer sb_7cyEmMkco216unjxIBct6XTQ","alt_header":"X-Sandbox-Token: sb_7cyEmMkco216unjxIBct6XTQ"}}Nel terminale conviene metterlo in una variabile (capitolo 2, punto 3):
TOKEN=$(curl -sS -X POST https://corso-api-json.giuseppebosi.com/api/v1/sandbox | jq -r .token)2. POST: creare un libro
Sezione intitolata “2. POST: creare un libro”curl -sS -i -X POST https://corso-api-json.giuseppebosi.com/api/v1/books \-H "Authorization: Bearer $TOKEN" \-H 'Content-Type: application/json' \-d '{"title": "Il mio primo libro", "author_id": 3, "category_id": 2, "price": 12.5, "pages": 180, "published_year": 2026, "attributes": {"format": "brossura", "ebook": true}, "tags": ["novità", "esordio"]}'- -X POST …/books
- POST sulla collezione: "aggiungi un elemento"
- -H "Authorization: Bearer $TOKEN"
- il token della sandbox; doppie virgolette per espandere la variabile
- -H 'Content-Type: application/json'
- il corpo è JSON
- -d '{…}'
- il nuovo libro.
author_idecategory_iddevono esistere (FK);isbnè opzionale: il server ne genera uno; gli a capo dentro gli apici singoli sono ammessi (con-dcurl li toglie)
HTTP/1.1 201 Createdlocation: https://corso-api-json.giuseppebosi.com/api/v1/books/81content-type: application/json
{"id":81,"title":"Il mio primo libro","isbn":"978-88-sandbox-81","author_id":3,"category_id":2,"price":12.5,"pages":180,"published_year":2026,"language":"it","in_stock":true,"attributes":{"format":"brossura","ebook":true},"created_at":"2026-09-18T20:03:40Z","reviews_count":0,"avg_rating":null,"tags":["esordio","novità"]}Tre cose: lo status è 201, non 200; l’header Location dice dove vive il nuovo elemento (/books/81); il corpo è l’oggetto come lo ha salvato il server, con i campi che ha aggiunto lui (id, isbn, created_at, language al default it).
3. PATCH: cambiare due campi
Sezione intitolata “3. PATCH: cambiare due campi”curl -sS -X PATCH https://corso-api-json.giuseppebosi.com/api/v1/books/81 \-H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \-d '{"price": 9.9, "in_stock": false}' | jq '{id, title, price, in_stock, tags}'- -X PATCH …/books/81
- sull'elemento, con i soli campi da cambiare
- {"price": 9.9, "in_stock": false}
- tutto il resto (titolo, tag, attributi…) resta com'era
{ "id": 81, "title": "Il mio primo libro", "price": 9.9, "in_stock": false, "tags": ["esordio", "novità"] }4. PUT: sostituire tutto
Sezione intitolata “4. PUT: sostituire tutto”curl -sS -X PUT https://corso-api-json.giuseppebosi.com/api/v1/books/81 \-H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \-d '{"title": "Il mio primo libro (2a ed.)", "author_id": 3, "category_id": 2, "price": 14}' \| jq '{id, title, price, pages, in_stock, tags, attributes}'- -X PUT
- sostituisce l'intera rappresentazione: il corpo deve contenere tutti i campi obbligatori (
title,author_id,category_id,price) - (niente pages, tags, attributes)
- e i campi omessi tornano al default: guarda la risposta
{ "id": 81, "title": "Il mio primo libro (2a ed.)", "price": 14.0, "pages": null, "in_stock": true, "tags": [], "attributes": {} }pages è diventato null, tags vuoto, attributes vuoto, in_stock è tornato true: era un PUT. Se volevi cambiare solo il titolo, serviva PATCH.
5. DELETE: due esiti
Sezione intitolata “5. DELETE: due esiti”curl -sS -i -X DELETE https://corso-api-json.giuseppebosi.com/api/v1/books/1 -H "Authorization: Bearer $TOKEN"curl -sS -i -X DELETE https://corso-api-json.giuseppebosi.com/api/v1/books/81 -H "Authorization: Bearer $TOKEN"- -X DELETE …/books/1
- il libro 1 compare in ordini esistenti (
order_items.book_id): la chiave esterna lo protegge - -X DELETE …/books/81
- il libro che abbiamo creato noi: nessun ordine lo cita
HTTP/1.1 409 Conflict{"error":{"code":"book_in_orders","message":"Il libro compare in ordini esistenti: la chiave esterna impedisce di cancellarlo"}}
HTTP/1.1 204 No Content204 = fatto, e non c’è corpo (attenzione a non chiamare .json() su una risposta vuota). Un secondo DELETE /books/81 darebbe 404: lo stato è lo stesso (idempotenza), cambia solo il codice.
6. Il dataset pubblico non cambia
Sezione intitolata “6. Il dataset pubblico non cambia”curl -sS 'https://corso-api-json.giuseppebosi.com/api/v1/books?q=mio%20primo' | jq .meta.total- (nessun -H Authorization)
- senza token leggi il dataset pubblico: il libro "Il mio primo libro" non esiste lì
- %20
- lo spazio codificato nella query string
07. Azzerare o eliminare
Sezione intitolata “7. Azzerare o eliminare”curl -sS -X POST https://corso-api-json.giuseppebosi.com/api/v1/sandbox/reset -H "Authorization: Bearer $TOKEN"curl -sS -i -X DELETE https://corso-api-json.giuseppebosi.com/api/v1/sandbox -H "Authorization: Bearer $TOKEN"- POST /sandbox/reset
- riporta la copia ai dati iniziali; il token resta valido
- DELETE /sandbox
- cancella la copia e invalida il token (
204). Per continuare, crea una sandbox nuova
Python e TypeScript
Sezione intitolata “Python e TypeScript”Il ciclo completo: crea sandbox → POST → PATCH → DELETE, con controllo dello status e lettura di Location.
# python3 scritture.pyimport httpx
base = "https://corso-api-json.giuseppebosi.com/api/v1"with httpx.Client(base_url=base) as c: token = c.post("/sandbox").raise_for_status().json()["token"] c.headers["Authorization"] = f"Bearer {token}" # da qui in poi tutte le richieste lo portano
nuovo = {"title": "Il mio primo libro", "author_id": 3, "category_id": 2, "price": 12.5, "tags": ["novità"]} r = c.post("/books", json=nuovo) # json= serializza e mette Content-Type: application/json r.raise_for_status() print(r.status_code, r.headers["location"]) # 201 …/api/v1/books/81 libro = r.json()
r = c.patch(f'/books/{libro["id"]}', json={"price": 9.9}) print(r.status_code, r.json()["price"]) # 200 9.9
r = c.delete(f'/books/{libro["id"]}') print(r.status_code, repr(r.text)) # 204 '' ← nessun corpo
r = c.delete("/books/1") # FK: è in ordini print(r.status_code, r.json()["error"]["code"]) # 409 book_in_orders
c.delete("/sandbox") # puliziaCosa dovresti vedere:
201 https://corso-api-json.giuseppebosi.com/api/v1/books/81200 9.9204 ''409 book_in_orders// node --experimental-strip-types scritture.tsconst base = "https://corso-api-json.giuseppebosi.com/api/v1";const token = (await (await fetch(base + "/sandbox", { method: "POST" })).json()).token;const headers = { Authorization: `Bearer ${token}`, "Content-Type": "application/json" };
const nuovo = { title: "Il mio primo libro", author_id: 3, category_id: 2, price: 12.5, tags: ["novità"] };let r = await fetch(base + "/books", { method: "POST", headers, body: JSON.stringify(nuovo) });if (!r.ok) throw new Error("HTTP " + r.status);console.log(r.status, r.headers.get("location")); // 201 …/api/v1/books/81const libro = await r.json();
r = await fetch(`${base}/books/${libro.id}`, { method: "PATCH", headers, body: JSON.stringify({ price: 9.9 }) });console.log(r.status, (await r.json()).price); // 200 9.9
r = await fetch(`${base}/books/${libro.id}`, { method: "DELETE", headers });console.log(r.status, JSON.stringify(await r.text())); // 204 "" ← nessun corpo: niente .json()
r = await fetch(`${base}/books/1`, { method: "DELETE", headers });console.log(r.status, (await r.json()).error.code); // 409 book_in_orders
await fetch(base + "/sandbox", { method: "DELETE", headers }); // puliziaCosa dovresti vedere:
201 https://corso-api-json.giuseppebosi.com/api/v1/books/81200 9.9204 ""409 book_in_ordersProva subito
Sezione intitolata “Prova subito”Con la sandbox creata dal pannello in alto:
Header della risposta
Header della risposta
Header della risposta
Header della risposta
Header della risposta
Esercizio
Sezione intitolata “Esercizio”Provalo online, senza installare nulla:
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/.
- Crea un cliente (
POST /api/v1/customersconname,email,city), poi crea un secondo cliente con la stessa email. Che status ottieni e con qualecode? - Crea un libro, poi fagli un
PUTche contiene solotitle,author_id,category_id,price. Confrontaattributesprima e dopo. Poi rifai la stessa modifica del titolo conPATCHsu un libro nuovo: cosa cambia? - Cancella la sandbox e riprova un
GET /api/v1/sandbox/mecon il vecchio token.
Soluzione
409 Conflict,code: "duplicate_email": l’email è unica nella tabella.- Dopo il
PUT,attributesè{}etagsè[]; dopo ilPATCHsono intatti. Regola: PUT = “ecco com’è ora l’oggetto, per intero”. 401concode: "invalid_token": la copia non esiste più.
Errori comuni
Sezione intitolata “Errori comuni”.json()su un 204: corpo vuoto →JSONDecodeError/SyntaxError: Unexpected end of JSON input. Controlla lo status prima.- PUT con corpo parziale credendo che sia un PATCH: dati azzerati.
- Token tra apici singoli in curl (
'Bearer $TOKEN'): 401. - Riusare un id dopo il reset:
POST /sandbox/resetriporta gli id al dataset iniziale; il libro 81 non esiste più. - Condividere il token (in uno screenshot, in un repo): chiunque può scrivere nella tua copia.
In sintesi
Sezione intitolata “In sintesi”POST /sandbox → token → Authorization: Bearer. POST crea (201 + Location), PUT sostituisce, PATCH ritocca, DELETE elimina (204). Le chiavi esterne proteggono i dati (409). Prossimo capitolo: tutti gli errori che un’API può rispondere, e come gestirli nel codice.