Vai al contenuto
code-to-code

Apro l'indice…

↑ ↓ per scegliere, Invio per aprire, Esc per chiudere

HTTP e API7. CRUD su un dizionariop. 173

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.

armadietti = { 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), }armadiettidict1235Armadiettoid1codice"A1"stazione_id1occupatoFalseArmadiettoid2codice"A2"stazione_id1occupatoTrueArmadiettoid3codice"B1"stazione_id3occupatoFalseArmadiettoid5codice"B2"stazione_id3occupatoTrue
L'archivio degli armadietti

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.

Python
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) + 1

I 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 clientLa richiestaLa mossa sul dizionarioLa risposta
Tutti gli armadietti (o solo alcuni)GET /armadiettifor e if sui valori200 e una lista
Un armadiettoGET /armadietti/2armadietti.get(2)200, oppure 404
Un armadietto nuovoPOST /armadiettiarmadietti[nuovo_id] = …201 e l'armadietto, con il suo id
Cambiare un armadiettoPUT /armadietti/2armadietti[2] = …200 e l'armadietto, oppure 404
Togliere un armadiettoDELETE /armadietti/2del 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.

Python
@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=3

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

Python
trovati = []
for armadietto in armadietti.values():
    if armadietto.stazione_id == stazione_id:
        trovati.append(armadietto)
return trovati

Con stazione_id=3, giro per giro:

Giroarmadiettostazione_id dell'armadietto uguale a 3?trovati dopo il giro
1l'armadietto 1no (è nella 1)vuota
2l'armadietto 2no (è nella 1)vuota
3l'armadietto 3sìl'armadietto 3
4l'armadietto 5sì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:

Python
@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 trovati

Due 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:

Python
@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 trovati

Leggi 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):

Terminale
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 scriveSe l'id c'èSe l'id non c'è
armadietti[id]l'armadiettoKeyError: nel server vero diventa un 500
armadietti.get(id)l'armadiettoNone

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 Error

Il 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:

Python
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:

  • raise esce dalla funzione come un return: 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.
Terminale
curl -i http://127.0.0.1:8000/armadietti/2
curl -i http://127.0.0.1:8000/armadietti/4
HTTP/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 Found

3 · POST, il 201 e l'id scelto dal server

Un armadietto nuovo, POST /armadietti, con il corpo in JSON:

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:

  1. il server sceglie l'id con prossimo_id(armadietti);
  2. costruisce l'Armadietto con quell'id e i dati arrivati;
  3. lo mette nel dizionario, alla chiave del suo id;
  4. lo restituisce.
Python
@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 armadietto

La 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:

Python
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:

Terminale
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:

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

Python
@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 armadietto

Tre dettagli:

  • L'id del nuovo armadietto viene dal percorso (armadietto_id), non dal corpo: il corpo non ha l'id.
  • La chiamata a trova_armadietto all'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:

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

archivio = { 1: Armadietto(id=1, codice="A1", stazione_id=1, occupato=False), 2: Armadietto(id=2, codice="A2", stazione_id=1, occupato=False), 3: Armadietto(id=3, codice="B1", stazione_id=3, occupato=False), 5: Armadietto(id=5, codice="B2", stazione_id=3, occupato=True), } prima = Armadietto(id=2, codice="A2", stazione_id=1, occupato=True) dopo = archivio[2]archivioprimadopodict1235Armadiettoid1codice"A1"stazione_id1occupatoFalseArmadiettoid2codice"A2"stazione_id1occupatoFalseArmadiettoid3codice"B1"stazione_id3occupatoFalseArmadiettoid5codice"B2"stazione_id3occupatoTrueArmadiettoid2codice"A2"stazione_id1occupatoTrue
Dopo la PUT: la scatola vecchia resta a prima

E la richiesta vera, con un armadietto che non c'è (il 4, tolto tanto tempo fa):

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

Python
@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'è, del dà 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.

Terminale
curl -i -X DELETE http://127.0.0.1:8000/armadietti/5
curl -i -X DELETE http://127.0.0.1:8000/armadietti/5
HTTP/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, 3

La 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):

Python
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 False

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

Python
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
True

Le 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:

Python
@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 armadietto

L'ordine nella PUT: 404 → 409 → lavoro. Prima «esiste?», poi «va in conflitto?», poi si fa.

Terminale
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

CodiceQuandoDove lo scrivi
200 OKVa tutto bene (la risposta c'è)Niente: è il codice di default
201 CreatedUn oggetto nuovo è stato creatoNel decoratore della POST: status_code=status.HTTP_201_CREATED
204 No ContentFatto, e non c'è niente da mostrareNel decoratore della DELETE: status_code=status.HTTP_204_NO_CONTENT
404 Not FoundL'id non c'èDentro la funzione: raise HTTPException(status_code=404, detail=…)
409 ConflictIl dato va in conflitto con uno già presenteDentro la funzione: raise HTTPException(status_code=409, detail=…)
422Il corpo o un parametro non è quello attesoNon 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.

CRUDHTTPIl dizionarioSQL
CrearePOST /armadiettiarmadietti[nuovo_id] = …INSERT
Leggere (lista)GET /armadiettifor e if sui valoriSELECT … WHERE …
Leggere (uno)GET /armadietti/2armadietti.get(2)SELECT … WHERE id = 2
CambiarePUT /armadietti/2armadietti[2] = …UPDATE
TogliereDELETE /armadietti/2del 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

  1. L'archivio è un dizionario id → oggetto. Cinque rotte, cinque mosse.
  2. GET lista: il caso «nessun filtro» per primo, con is None; un if dentro il for. Nessun risultato è 200 e [], mai un 404.
  3. GET con l'id: get, poi is None, poi raise HTTPException(status_code=404, …). Prima il 404, poi il lavoro.
  4. POST: l'id lo sceglie il server (prossimo_id), l'oggetto con l'id va nel dizionario, 201 nel decoratore.
  5. PUT: tutti i campi, l'id dal percorso, scatola nuova alla stessa chiave. DELETE: del, niente return, 204, e la seconda volta 404.
  6. 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.