CRUD su un dizionario
Cinque rotte, cinque mosse su un dizionario
- 25 minuti di lettura
Nelle stazioni della Linea Menta ci sono gli armadietti: i passeggeri ci lasciano una valigia per qualche ora. Marta Villa, capostazione di Piazza Query, vuole un'API per gestirli. Cinque domande, e basta:
- «quali armadietti ci sono, e quali sono liberi?»
- «com'è fatto l'armadietto 2?»
- «ne abbiamo montato uno nuovo»
- «l'armadietto 2 ora è libero»
- «l'armadietto 5 è stato tolto»
Sono le cose che si fanno con quasi ogni archivio del mondo: Create (creare), Read (leggere), Update (cambiare), Delete (togliere). Da qui il nome CRUD. (Leggere ha due rotte, la lista e uno solo: per questo le rotte sono cinque.) In questo capitolo scrivi le rotte che le fanno, e l'archivio è un dizionario Python. Niente database: quello arriva nel libro Il database nell'API.
Dai capitoli precedenti ti servono tre cose: la forma della chiamata (dove FastAPI cerca i dati: percorso, query, corpo), Pydantic (gli stampi Armadietto e ArmadiettoNuovo, già scritti) e verbi e codici (200, 201, 204, 404, 409). Qui non si rispiega niente di nuovo su quelle: si usano.
L'archivio: un dizionario id → oggetto
Lo disegniamo come in Etichette e scatole. L'etichetta armadietti è attaccata a un dizionario; ogni chiave è l'id dell'armadietto, ogni valore è la sua scatola, un oggetto Armadietto.
Il 4 non c'è: l'armadietto 4 è stato tolto, e il suo id non si riusa. Gli id di un archivio vero hanno quasi sempre dei buchi. Tienilo a mente: ci torniamo alla POST.
Ogni oggetto porta dentro anche il proprio id (Armadietto(id=2, codice="A2", …)): la chiave del dizionario e l'id dell'oggetto sono lo stesso numero.
Nel codice, in tre pezzi: gli stampi, il dizionario e una funzione che sceglie il prossimo id.
from fastapi import FastAPI, HTTPException, status
from pydantic import BaseModel
app = FastAPI(title="Gli armadietti della Linea Menta")
class ArmadiettoNuovo(BaseModel):
"""Quello che manda il client: senza id."""
codice: str
stazione_id: int
occupato: bool
class Armadietto(ArmadiettoNuovo):
"""Quello che il server salva e restituisce: gli stessi campi, più l'id."""
id: int
# L'archivio: id -> Armadietto. Il 4 è stato tolto: gli id sono 1, 2, 3 e 5.
armadietti: dict[int, Armadietto] = {
1: Armadietto(id=1, codice="A1", stazione_id=1, occupato=False),
2: Armadietto(id=2, codice="A2", stazione_id=1, occupato=True),
3: Armadietto(id=3, codice="B1", stazione_id=3, occupato=False),
5: Armadietto(id=5, codice="B2", stazione_id=3, occupato=True),
}
def prossimo_id(dizionario: dict) -> int:
"""Il più grande id che c'è, più uno. Un dizionario vuoto parte da 1."""
return max(dizionario, default=0) + 1I due stampi sono quelli del capitolo su Pydantic: ArmadiettoNuovo è la forma senza id (quello che il client manda), Armadietto è la stessa forma con l'id (quello che il server risponde). L'id non lo decide il client: lo decide il server.
Le cinque rotte e le loro mosse
Ogni rotta è una mossa sul dizionario: le stesse della tabella finale di I dizionari.
| Cosa vuole il client | La richiesta | La mossa sul dizionario | La risposta |
|---|---|---|---|
| Tutti gli armadietti (o solo alcuni) | GET /armadietti | for e if sui valori | 200 e una lista |
| Un armadietto | GET /armadietti/2 | armadietti.get(2) | 200, oppure 404 |
| Un armadietto nuovo | POST /armadietti | armadietti[nuovo_id] = … | 201 e l'armadietto, con il suo id |
| Cambiare un armadietto | PUT /armadietti/2 | armadietti[2] = … | 200 e l'armadietto, oppure 404 |
| Togliere un armadietto | DELETE /armadietti/2 | del armadietti[2] | 204 e niente corpo, oppure 404 |
Le prendiamo una alla volta, dalla più semplice. Ogni rotta aggiunge una cosa sola.
1 · GET sulla lista, e il setaccio
La rotta più semplice: restituisce tutto.
@app.get("/armadietti")
def lista_armadietti() -> list[Armadietto]:
return list(armadietti.values())armadietti.values() sono le scatole, senza le chiavi; list(…) ne fa una lista, e FastAPI la trasforma in JSON.
Marta però non vuole vederli tutti: a Largo Lista (la stazione 3) le interessano solo quelli della sua stazione. La richiesta diventa:
GET /armadietti?stazione_id=3Il filtro sta nella query, dopo il ?, e è facoltativo: senza ? si ricevono tutti. Nel def si scrive con = None (è la regola del capitolo La forma della chiamata).
Per tenere solo gli armadietti giusti si usa il setaccio: una lista vuota, un for sui valori, un if che decide chi passa, append per far passare.
trovati = []
for armadietto in armadietti.values():
if armadietto.stazione_id == stazione_id:
trovati.append(armadietto)
return trovatiCon stazione_id=3, giro per giro:
| Giro | armadietto | stazione_id dell'armadietto uguale a 3? | trovati dopo il giro |
|---|---|---|---|
| 1 | l'armadietto 1 | no (è nella 1) | vuota |
| 2 | l'armadietto 2 | no (è nella 1) | vuota |
| 3 | l'armadietto 3 | sì | l'armadietto 3 |
| 4 | l'armadietto 5 | sì | gli armadietti 3 e 5 |
Ma manca un caso: nessun filtro. Se stazione_id vale None, il confronto armadietto.stazione_id == None non è mai vero, e la lista torna vuota. Il caso «nessun filtro» va trattato per primo, con is None:
@app.get("/armadietti")
def lista_armadietti(stazione_id: int | None = None) -> list[Armadietto]:
if stazione_id is None:
return list(armadietti.values())
trovati = []
for armadietto in armadietti.values():
if armadietto.stazione_id == stazione_id:
trovati.append(armadietto)
return trovatiDue filtri insieme
Marta vuole anche sapere quali sono liberi: GET /armadietti?stazione_id=3&occupato=false. Ogni armadietto deve passare tutti e due i filtri; un filtro assente lascia passare tutti. Si scrive una domanda per filtro e le si mette insieme con and:
@app.get("/armadietti")
def lista_armadietti(stazione_id: int | None = None, occupato: bool | None = None) -> list[Armadietto]:
if stazione_id is None and occupato is None:
return list(armadietti.values())
trovati = []
for armadietto in armadietti.values():
passa_stazione = stazione_id is None or armadietto.stazione_id == stazione_id
passa_occupato = occupato is None or armadietto.occupato == occupato
if passa_stazione and passa_occupato:
trovati.append(armadietto)
return trovatiLeggi passa_stazione così: «il filtro non c'è, oppure la stazione dell'armadietto è quella cercata». Se il filtro non c'è, la domanda è già «sì». Le due righe passa_… sono due booleani con un nome: il if sotto si legge come una frase.
Il nome del filtro nell'indirizzo (stazione_id) e quello dell'argomento nel def sono lo stesso, lettera per lettera: è così che FastAPI li collega.
Proviamo. Nel primo terminale il server (fastapi dev prove/armadietti.py), nel secondo curl (venv acceso):
curl -s http://127.0.0.1:8000/armadietti | python3 -m json.tool
curl -s "http://127.0.0.1:8000/armadietti?stazione_id=3"
curl -s "http://127.0.0.1:8000/armadietti?stazione_id=3&occupato=false"
curl -s "http://127.0.0.1:8000/armadietti?stazione_id=9"[
{
"codice": "A1",
"stazione_id": 1,
"occupato": false,
"id": 1
},
{
"codice": "A2",
"stazione_id": 1,
"occupato": true,
"id": 2
},
{
"codice": "B1",
"stazione_id": 3,
"occupato": false,
"id": 3
},
{
"codice": "B2",
"stazione_id": 3,
"occupato": true,
"id": 5
}
]
[{"codice":"B1","stazione_id":3,"occupato":false,"id":3},{"codice":"B2","stazione_id":3,"occupato":true,"id":5}]
[{"codice":"B1","stazione_id":3,"occupato":false,"id":3}]
[]Guarda l'ultima: la stazione 9 non ha armadietti, e la risposta è [], con il codice 200. Nessun risultato non è un errore: il client ha chiesto «gli armadietti della stazione 9» e la risposta onesta è «nessuno». Il 404 si usa quando chiedi una cosa precisa che non c'è, come vedi adesso.
2 · GET con l'id, e il 404
Adesso l'armadietto 2: GET /armadietti/2. Il 2 sta nel percorso, tra graffe nel decoratore e con lo stesso nome nel def (di nuovo la forma della chiamata).
Per leggere dal dizionario hai due modi, e rispondono in modo diverso quando la chiave manca (la tabella delle sei mosse in I dizionari):
| Si scrive | Se l'id c'è | Se l'id non c'è |
|---|---|---|
armadietti[id] | l'armadietto | KeyError: nel server vero diventa un 500 |
armadietti.get(id) | l'armadietto | None |
Se una rotta legge con le quadre (return armadietti[armadietto_id]) e il client chiede l'armadietto 4, il server risponde così (provato con un TestClient che non rilancia l'errore):
500 Internal Server ErrorIl 500 vuol dire «ho sbagliato io, il server». Ma l'errore l'ha fatto il client, chiedendo un id che non c'è.
Un id sbagliato non è un guaio del server: è un errore del client, e deve ricevere una risposta chiara, il 404 Not Found. Quindi si usa get, si guarda se è None, e in quel caso si solleva un'eccezione che FastAPI trasforma in un 404:
def trova_armadietto(armadietto_id: int) -> Armadietto:
armadietto = armadietti.get(armadietto_id)
if armadietto is None:
raise HTTPException(status_code=404, detail="Armadietto non trovato")
return armadietto
@app.get("/armadietti/{armadietto_id}")
def leggi_armadietto(armadietto_id: int) -> Armadietto:
return trova_armadietto(armadietto_id)Tre cose da notare:
raiseesce dalla funzione come unreturn: se l'armadietto non c'è, le righe dopo non girano mai. L'errore è nelle eccezioni: qui lo lanci tu apposta.detailè il messaggio che torna al client, dentro un JSON:{"detail": "Armadietto non trovato"}.- La ricerca sta in una funzione a parte,
trova_armadietto, perché ti serve ancora, nella PUT e nella DELETE. Scritta una volta, riusata tre.
curl -i http://127.0.0.1:8000/armadietti/2
curl -i http://127.0.0.1:8000/armadietti/4HTTP/1.1 200 OK
date: Thu, 19 Nov 2026 17:58:30 GMT
server: uvicorn
content-length: 54
content-type: application/json
{"codice":"A2","stazione_id":1,"occupato":true,"id":2}HTTP/1.1 404 Not Found
date: Thu, 19 Nov 2026 17:58:30 GMT
server: uvicorn
content-length: 35
content-type: application/json
{"detail":"Armadietto non trovato"}Nel terminale del server compare, per ogni richiesta, una riga con il codice (è la richiesta vista dall'altra parte):
INFO: 127.0.0.1:63072 - "GET /armadietti/2 HTTP/1.1" 200 OK
INFO: 127.0.0.1:63073 - "GET /armadietti/4 HTTP/1.1" 404 Not Found3 · POST, il 201 e l'id scelto dal server
Un armadietto nuovo, POST /armadietti, con il corpo in JSON:
{"codice": "C1", "stazione_id": 4, "occupato": false}Il client non manda l'id: lo sceglie il server. Per questo il def riceve un ArmadiettoNuovo (senza id) e la risposta è un Armadietto (con l'id). Il lavoro, in quattro mosse:
- il server sceglie l'id con
prossimo_id(armadietti); - costruisce l'
Armadiettocon quell'id e i dati arrivati; - lo mette nel dizionario, alla chiave del suo id;
- lo restituisce.
@app.post("/armadietti", status_code=status.HTTP_201_CREATED)
def nuovo_armadietto(dati: ArmadiettoNuovo) -> Armadietto:
armadietto = Armadietto(
id=prossimo_id(armadietti),
codice=dati.codice,
stazione_id=dati.stazione_id,
occupato=dati.occupato,
)
armadietti[armadietto.id] = armadietto
return armadiettoLa riga che salva è armadietti[armadietto.id] = armadietto: nel dizionario va l'oggetto con l'id (armadietto), non i dati arrivati (dati, che l'id non ce l'hanno).
Il 201 Created («creato») si scrive nel decoratore, con status_code=status.HTTP_201_CREATED. Il nome si importa da fastapi, come HTTPException: al posto del numero 201, un nome che si legge.
Perché prossimo_id e non «quanti sono più uno»
Nel dizionario ci sono quattro armadietti, con id 1, 2, 3 e 5. Quanto fa «quanti sono più uno»? 5. Ma l'armadietto 5 esiste già: scrivere armadietti[5] = … lo sovrascrive, e un armadietto sparisce senza che nessuno lo sappia. prossimo_id prende il più grande id che c'è e aggiunge uno:
from fastapi.testclient import TestClient
import armadietti
from armadietti import prossimo_id
print("len + 1: ", len(armadietti.armadietti) + 1)
print("prossimo_id: ", prossimo_id(armadietti.armadietti))
print("dizionario vuoto:", prossimo_id({}))
client = TestClient(armadietti.app)
corpo = {"codice": "C1", "stazione_id": 4, "occupato": False}
risposta = client.post("/armadietti", json=corpo)
print(risposta.status_code, risposta.json())
print(6 in armadietti.armadietti)
print(list(armadietti.armadietti))len + 1: 5
prossimo_id: 6
dizionario vuoto: 1
201 {'codice': 'C1', 'stazione_id': 4, 'occupato': False, 'id': 6}
True
[1, 2, 3, 5, 6](TestClient è un client che chiama l'API senza accendere il server: lo usano i test, e lo vedi anche qui.)
Con curl, lo stesso:
curl -i -X POST http://127.0.0.1:8000/armadietti -H "Content-Type: application/json" -d '{"codice": "C1", "stazione_id": 4, "occupato": false}'HTTP/1.1 201 Created
date: Thu, 19 Nov 2026 17:58:30 GMT
server: uvicorn
content-length: 55
content-type: application/json
{"codice":"C1","stazione_id":4,"occupato":false,"id":6}E se nel corpo manca un campo, ci pensa FastAPI prima ancora di entrare nella funzione:
curl -i -X POST http://127.0.0.1:8000/armadietti -H "Content-Type: application/json" -d '{"codice": "C2", "stazione_id": 4}'HTTP/1.1 422 Unprocessable Entity
date: Thu, 19 Nov 2026 17:58:30 GMT
server: uvicorn
content-length: 120
content-type: application/json
{"detail":[{"type":"missing","loc":["body","occupato"],"msg":"Field required","input":{"codice":"C2","stazione_id":4}}]}Il 422 lo scrive FastAPI per te (come si legge: Pydantic). La tua funzione non gira nemmeno.
4 · PUT, la scatola nuova
Un passeggero ha ritirato la valigia dall'armadietto 2: adesso è libero. Con la PUT il client manda l'armadietto com'è adesso, tutto intero:
PUT /armadietti/2
{"codice": "A2", "stazione_id": 1, "occupato": false}Qui ci sono due pezzi di dati: l'id nel percorso (quale armadietto) e il resto nel corpo (com'è adesso). Nel def stanno tutti e due, uno dopo l'altro.
La PUT non ritocca il vecchio armadietto: ne costruisce uno nuovo e lo mette nella stessa chiave, al posto del vecchio. Una scatola nuova, la stessa etichetta.
@app.put("/armadietti/{armadietto_id}")
def sostituisci_armadietto(armadietto_id: int, dati: ArmadiettoNuovo) -> Armadietto:
trova_armadietto(armadietto_id) # prima il 404
armadietto = Armadietto(
id=armadietto_id,
codice=dati.codice,
stazione_id=dati.stazione_id,
occupato=dati.occupato,
)
armadietti[armadietto_id] = armadietto
return armadiettoTre dettagli:
- L'
iddel nuovo armadietto viene dal percorso (armadietto_id), non dal corpo: il corpo non ha l'id. - La chiamata a
trova_armadiettoall'inizio fa il 404 (se l'armadietto non c'è, la funzione si ferma lì), e il suo risultato non serve: basta che lanci l'errore. Il motivo è sotto, nella regola «prima il 404». - Nel corpo vanno tutti i campi, anche quelli che non cambiano. Per cambiarne uno solo esiste un altro verbo, il PATCH: lo trovi come bonus in fondo a questa pagina.
Il disegno, prima e dopo:
PRIMA DOPO
armadietti armadietti
┌─────┬─────────────────────────┐ ┌─────┬─────────────────────────┐
│ 1 │ A1 stazione 1 libero │ │ 1 │ A1 stazione 1 libero │
│ 2 │ A2 stazione 1 pieno │ ───▶ │ 2 │ A2 stazione 1 libero │ ◀ scatola nuova
│ 3 │ B1 stazione 3 libero │ │ 3 │ B1 stazione 3 libero │
│ 5 │ B2 stazione 3 pieno │ │ 5 │ B2 stazione 3 pieno │
└─────┴─────────────────────────┘ └─────┴─────────────────────────┘
chiavi: 1, 2, 3, 5 chiavi: 1, 2, 3, 5 (le stesse)Le chiavi non cambiano: cambia la scatola dietro la chiave 2. Lo si vede anche dal codice:
from fastapi.testclient import TestClient
import armadietti
archivio = armadietti.armadietti
prima = archivio[2]
print("prima:", prima)
client = TestClient(armadietti.app)
risposta = client.put("/armadietti/2", json={"codice": "A2", "stazione_id": 1, "occupato": False})
print(risposta.status_code, risposta.json())
dopo = archivio[2]
print("dopo: ", dopo)
print("stessa scatola?", dopo is prima)
print("la scatola vecchia dice ancora:", prima.occupato)
print("chiavi:", list(archivio))prima: codice='A2' stazione_id=1 occupato=True id=2
200 {'codice': 'A2', 'stazione_id': 1, 'occupato': False, 'id': 2}
dopo: codice='A2' stazione_id=1 occupato=False id=2
stessa scatola? False
la scatola vecchia dice ancora: True
chiavi: [1, 2, 3, 5]Il disegno.
E la richiesta vera, con un armadietto che non c'è (il 4, tolto tanto tempo fa):
curl -i -X PUT http://127.0.0.1:8000/armadietti/2 -H "Content-Type: application/json" -d '{"codice": "A2", "stazione_id": 1, "occupato": false}'
curl -i -X PUT http://127.0.0.1:8000/armadietti/4 -H "Content-Type: application/json" -d '{"codice": "A4", "stazione_id": 1, "occupato": false}'HTTP/1.1 200 OK
date: Thu, 19 Nov 2026 17:58:30 GMT
server: uvicorn
content-length: 55
content-type: application/json
{"codice":"A2","stazione_id":1,"occupato":false,"id":2}HTTP/1.1 404 Not Found
date: Thu, 19 Nov 2026 17:58:30 GMT
server: uvicorn
content-length: 35
content-type: application/json
{"detail":"Armadietto non trovato"}5 · DELETE e il 204
L'armadietto 5 è stato tolto. DELETE /armadietti/5: il client non manda niente nel corpo, e non si aspetta niente indietro, solo la conferma. Il codice è 204 No Content («fatto, e non c'è niente da mostrare»).
@app.delete("/armadietti/{armadietto_id}", status_code=status.HTTP_204_NO_CONTENT)
def togli_armadietto(armadietto_id: int) -> None:
trova_armadietto(armadietto_id) # prima il 404
del armadietti[armadietto_id]- Il 204 si scrive nel decoratore, come il 201.
- La funzione non fa
return: il 204 non ha corpo. Per questo la freccia dice-> None. del armadietti[armadietto_id]toglie la chiave e la sua scatola. Se la chiave non c'è,deldàKeyError: per questo il controllo viene prima.
La seconda volta che chiedi la stessa DELETE, l'armadietto non c'è più, e la risposta è un 404: lo vedi qui sotto, con la stessa richiesta fatta due volte.
curl -i -X DELETE http://127.0.0.1:8000/armadietti/5
curl -i -X DELETE http://127.0.0.1:8000/armadietti/5HTTP/1.1 204 No Content
date: Thu, 19 Nov 2026 17:58:30 GMT
server: uvicorn
content-type: application/json
HTTP/1.1 404 Not Found
date: Thu, 19 Nov 2026 17:58:30 GMT
server: uvicorn
content-length: 35
content-type: application/json
{"detail":"Armadietto non trovato"}Il disegno: via la chiave e la sua scatola.
PRIMA DOPO del armadietti[5]
armadietti armadietti
┌─────┬─────────────────────────┐ ┌─────┬─────────────────────────┐
│ 1 │ A1 stazione 1 libero │ │ 1 │ A1 stazione 1 libero │
│ 2 │ A2 stazione 1 pieno │ │ 2 │ A2 stazione 1 pieno │
│ 3 │ B1 stazione 3 libero │ │ 3 │ B1 stazione 3 libero │
│ 5 │ B2 stazione 3 pieno │ └─────┴─────────────────────────┘
└─────┴─────────────────────────┘ chiavi: 1, 2, 3La regola: prima il 404, poi il lavoro
In tutte e tre le rotte che hanno un id (GET, PUT, DELETE) la prima cosa è la stessa: «esiste, questo id?». Se no, 404 e la funzione finisce. Solo dopo si lavora. È una regola sola, e ti salva da due guai: un KeyError che diventa un 500, e una PUT che crea un armadietto fantasma.
arriva la richiesta
│
l'id c'è nel dizionario?
│ │
no sì
│ │
raise HTTPException il lavoro (leggi, sostituisci, togli)
404, e finisce │
return (o niente, nella DELETE)6 · Il 409, un codice già usato
Una cosa manca. In ogni stazione l'armadietto ha un codice che si legge sulla porta: due armadietti con lo stesso codice sono un disastro (un passeggero apre l'armadietto di un altro). Se il client manda un codice che esiste già, il server rifiuta con un 409 Conflict («la richiesta è giusta, ma va in conflitto con quello che c'è»).
La domanda «questo codice ce l'ha già un altro armadietto?» diventa una funzione, con un for che parte dai valori (la chiave del dizionario è l'id, non il codice):
def codice_gia_usato(codice: str, tranne_id: int | None = None) -> bool:
for altro in armadietti.values():
if altro.codice == codice and altro.id != tranne_id:
return True
return FalseA cosa serve tranne_id? A una cosa che si vede nella PUT. Se Marta rimanda l'armadietto 3 con il suo codice B1 (cambia solo occupato), il codice «esiste già»: è proprio il suo. Non è un conflitto. Con tranne_id=3 il for salta l'armadietto 3, e rimangono solo gli altri.
from armadietti import codice_gia_usato
print(codice_gia_usato("A1"))
print(codice_gia_usato("Z9"))
print(codice_gia_usato("A1", tranne_id=1))
print(codice_gia_usato("A1", tranne_id=3))True
False
False
TrueLe quattro righe, una per una: A1 è usato (dall'1); Z9 no; A1 è usato ma proprio dall'armadietto 1, e chi chiede è l'1, quindi nessun conflitto; A1 è usato dall'1 e chi chiede è il 3: conflitto.
Dentro la POST non c'è tranne_id, perché nessun armadietto è «sé stesso»: l'armadietto non c'è ancora. Dentro la PUT c'è, ed è l'id del percorso. Le due rotte diventano, con il 409 aggiunto:
@app.post("/armadietti", status_code=status.HTTP_201_CREATED)
def nuovo_armadietto(dati: ArmadiettoNuovo) -> Armadietto:
if codice_gia_usato(dati.codice):
raise HTTPException(status_code=409, detail="Codice già usato da un altro armadietto")
armadietto = Armadietto(
id=prossimo_id(armadietti),
codice=dati.codice,
stazione_id=dati.stazione_id,
occupato=dati.occupato,
)
armadietti[armadietto.id] = armadietto
return armadietto
@app.put("/armadietti/{armadietto_id}")
def sostituisci_armadietto(armadietto_id: int, dati: ArmadiettoNuovo) -> Armadietto:
trova_armadietto(armadietto_id) # prima il 404
if codice_gia_usato(dati.codice, tranne_id=armadietto_id):
raise HTTPException(status_code=409, detail="Codice già usato da un altro armadietto")
armadietto = Armadietto(
id=armadietto_id,
codice=dati.codice,
stazione_id=dati.stazione_id,
occupato=dati.occupato,
)
armadietti[armadietto_id] = armadietto
return armadiettoL'ordine nella PUT: 404 → 409 → lavoro. Prima «esiste?», poi «va in conflitto?», poi si fa.
curl -i -X POST http://127.0.0.1:8000/armadietti -H "Content-Type: application/json" -d '{"codice": "A1", "stazione_id": 4, "occupato": false}'
curl -i -X PUT http://127.0.0.1:8000/armadietti/3 -H "Content-Type: application/json" -d '{"codice": "A1", "stazione_id": 3, "occupato": false}'HTTP/1.1 409 Conflict
date: Thu, 19 Nov 2026 17:58:30 GMT
server: uvicorn
content-length: 53
content-type: application/json
{"detail":"Codice già usato da un altro armadietto"}HTTP/1.1 409 Conflict
date: Thu, 19 Nov 2026 17:58:30 GMT
server: uvicorn
content-length: 53
content-type: application/json
{"detail":"Codice già usato da un altro armadietto"}I codici di questo capitolo
| Codice | Quando | Dove lo scrivi |
|---|---|---|
| 200 OK | Va tutto bene (la risposta c'è) | Niente: è il codice di default |
| 201 Created | Un oggetto nuovo è stato creato | Nel decoratore della POST: status_code=status.HTTP_201_CREATED |
| 204 No Content | Fatto, e non c'è niente da mostrare | Nel decoratore della DELETE: status_code=status.HTTP_204_NO_CONTENT |
| 404 Not Found | L'id non c'è | Dentro la funzione: raise HTTPException(status_code=404, detail=…) |
| 409 Conflict | Il dato va in conflitto con uno già presente | Dentro la funzione: raise HTTPException(status_code=409, detail=…) |
| 422 | Il corpo o un parametro non è quello atteso | Non lo scrivi: lo fa FastAPI |
La regola per scegliere dove scriverlo: i codici di successo (201, 204) si scrivono nel decoratore; i codici di errore (404, 409) si sollevano dentro la funzione.
CRUD, SQL e HTTP: la stessa cosa in tre lingue
Tra qualche capitolo l'archivio non sarà più un dizionario ma una tabella di PostgreSQL, e le rotte resteranno identiche. Cambierà solo la riga in mezzo.
| CRUD | HTTP | Il dizionario | SQL |
|---|---|---|---|
| Creare | POST /armadietti | armadietti[nuovo_id] = … | INSERT |
| Leggere (lista) | GET /armadietti | for e if sui valori | SELECT … WHERE … |
| Leggere (uno) | GET /armadietti/2 | armadietti.get(2) | SELECT … WHERE id = 2 |
| Cambiare | PUT /armadietti/2 | armadietti[2] = … | UPDATE |
| Togliere | DELETE /armadietti/2 | del armadietti[2] | DELETE |
Le quattro parole SQL sono nel libro SQL. Quando le avrai viste, le rotte che scrivi adesso saranno la parte più facile.
Il bonus: PATCH
Il PUT manda tutto. Se vuoi cambiare un campo solo (occupato), c'è il verbo PATCH: nel corpo vanno solo i campi che cambiano, e il server tiene gli altri. Si scrive meno, ma i campi sono tutti facoltativi, e la logica si complica. In questo capitolo non lo scrivi: lo trovi in InfoMenta, PATCH /treni/{treno_id}, da provare con curl.
E quando riaccendi il server?
Un dizionario vive nella memoria del programma. Quando il server si spegne (Ctrl+C), o si riavvia (e fastapi dev si riavvia a ogni salvataggio del file), il dizionario torna com'era nel codice: tutto quello che avevi aggiunto, cambiato o tolto sparisce. Per un archivio vero non va bene, e di questo parla il libro Il database nell'API: i dati vanno in un posto che non si spegne.
Ricorda
- L'archivio è un dizionario
id → oggetto. Cinque rotte, cinque mosse. - GET lista: il caso «nessun filtro» per primo, con
is None; unifdentro ilfor. Nessun risultato è 200 e[], mai un 404. - GET con l'id:
get, poiis None, poiraise HTTPException(status_code=404, …). Prima il 404, poi il lavoro. - POST: l'id lo sceglie il server (
prossimo_id), l'oggetto con l'id va nel dizionario, 201 nel decoratore. - PUT: tutti i campi, l'id dal percorso, scatola nuova alla stessa chiave. DELETE:
del, nientereturn, 204, e la seconda volta 404. - 409: il conflitto con un dato che c'è già (e nella PUT, «tranne sé stesso»).
Nel prossimo capitolo, Il contratto, si fa il passo opposto: le stesse cinque rotte si progettano prima di scriverle. Intanto, gli esercizi spiegati fanno vedere le stesse mosse una per una, e poi tocca alla palestra.