Salta ai contenuti

6. Sandbox e scritture

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

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.

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.

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.

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

La tua sandbox

Nessuna sandbox attiva in questo browser.

terminale
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 Created
content-type: application/json
cache-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):

Finestra del terminale
TOKEN=$(curl -sS -X POST https://corso-api-json.giuseppebosi.com/api/v1/sandbox | jq -r .token)
terminale
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_id e category_id devono esistere (FK); isbn è opzionale: il server ne genera uno; gli a capo dentro gli apici singoli sono ammessi (con -d curl li toglie)
HTTP/1.1 201 Created
location: https://corso-api-json.giuseppebosi.com/api/v1/books/81
content-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).

terminale
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à"] }
terminale
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.

terminale
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 Content

204 = 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.

terminale
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
0
terminale
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

Il ciclo completo: crea sandbox → POST → PATCH → DELETE, con controllo dello status e lettura di Location.

# python3 scritture.py
import 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") # pulizia

Cosa dovresti vedere:

201 https://corso-api-json.giuseppebosi.com/api/v1/books/81
200 9.9
204 ''
409 book_in_orders

Con la sandbox creata dal pannello in alto:

POST/api/v1/books— crea un libro (guarda status 201 e l'header Location)
Serve un token sandbox: crealo dal pannello La tua sandbox (viene salvato nel browser).
PATCH/api/v1/books/81— modifica due campi del libro 81 (se non esiste, crealo prima)
Serve un token sandbox: crealo dal pannello La tua sandbox (viene salvato nel browser).
DELETE/api/v1/books/1— prova a cancellare il libro 1: 409
Serve un token sandbox: crealo dal pannello La tua sandbox (viene salvato nel browser).
DELETE/api/v1/books/81— cancella il libro 81: 204, corpo vuoto
Serve un token sandbox: crealo dal pannello La tua sandbox (viene salvato nel browser).
POST/api/v1/books— lo stesso POST senza token: 401

Provalo online, senza installare nulla:

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

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

  1. Crea un cliente (POST /api/v1/customers con name, email, city), poi crea un secondo cliente con la stessa email. Che status ottieni e con quale code?
  2. Crea un libro, poi fagli un PUT che contiene solo title, author_id, category_id, price. Confronta attributes prima e dopo. Poi rifai la stessa modifica del titolo con PATCH su un libro nuovo: cosa cambia?
  3. Cancella la sandbox e riprova un GET /api/v1/sandbox/me con il vecchio token.
Soluzione
  1. 409 Conflict, code: "duplicate_email": l’email è unica nella tabella.
  2. Dopo il PUT, attributes è {} e tags è []; dopo il PATCH sono intatti. Regola: PUT = “ecco com’è ora l’oggetto, per intero”.
  3. 401 con code: "invalid_token": la copia non esiste più.
  • .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/reset riporta 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.

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.