La forma della chiamata
Percorso, query, corpo. FastAPI capisce dove guardare dal def
- 12 minuti di lettura
Nei capitoli 1–3 hai fatto domande a InfoMenta. I dati della domanda viaggiavano in tre posti diversi:
GET /stazioni/3 il 3 sta nel percorso
GET /viaggio?da=1&a=5 da e a stanno nella query, dopo il ?
POST /treni + un JSON il treno nuovo sta nel corpoAdesso sei dall'altra parte del filo: scrivi tu la funzione che risponde. Come ci arrivano, quei dati, dentro la funzione?
Non li vai a cercare tu. Li dichiari nella riga del def, e FastAPI li va a prendere al posto giusto. Ecco le tre rotte di InfoMenta che rispondevano a quelle domande (apri palestra/infomenta.py nello zip del capitolo 1 e cercale):
@app.get("/stazioni/{stazione_id}")
def leggi_stazione(stazione_id: int) -> Stazione:
...
@app.get("/viaggio")
def viaggio(da: int, a: int) -> dict:
...
@app.post("/treni", status_code=status.HTTP_201_CREATED)
def nuovo_treno(dati: TrenoNuovo) -> Treno:
...I tre puntini stanno per il codice dentro la funzione: in questo capitolo guardiamo solo le due righe sopra. (Nel file vero i decoratori hanno anche tags=[…], che serve solo a raggruppare le rotte in /docs: qui li lascio fuori. Il status_code del 201 è del capitolo CRUD su un dizionario.)
La regola, in tre righe
FastAPI capisce dove guardare dal def. Per ogni argomento della funzione si fa una domanda sola: dove sta questo dato?
Nel def c'è… | FastAPI guarda… | In InfoMenta |
|---|---|---|
| un nome che compare anche tra graffe nel percorso del decoratore | nel percorso | stazione_id: int, con "/stazioni/{stazione_id}" |
un nome che non è nel percorso, con un tipo semplice (int, str, bool) | nella query | da: int e a: int |
un nome che ha per tipo uno stampo (una classe BaseModel) | nel corpo | dati: TrenoNuovo |
Non c'è altro da scrivere: niente da importare, niente da configurare. Le tre regole stanno tutte nel decoratore e nella riga del def.
Il disegno
Due richieste, e le righe che le ricevono (sono un esempio: la prima rotta, in InfoMenta, non c'è). Il def si può scrivere su più righe, un argomento per riga: per Python è uguale, e si legge meglio.
GET /stazioni/3/treni?tipo=tram
@app.get("/stazioni/{stazione_id}/treni")
def treni_della_stazione(
stazione_id: int, ◀── 3 PERCORSO
tipo: str | None = None, ◀── "tram" QUERY
) -> list[Treno]:
PUT /treni/5
corpo: {"codice": "M12", "vagoni": 4, …}
@app.put("/treni/{treno_id}")
def sostituisci_treno(
treno_id: int, ◀── 5 PERCORSO
dati: TrenoNuovo, ◀── il JSON CORPO
) -> Treno:FastAPI legge la richiesta, prende ogni pezzo, lo controlla, lo converte, e solo alla fine chiama la tua funzione con gli argomenti già pieni. Quando la funzione parte, stazione_id vale già 3, un numero.
Il percorso: lo stesso nome, due volte
@app.get("/stazioni/{stazione_id}")
def leggi_stazione(stazione_id: int) -> Stazione:Le graffe nel decoratore dicono «qui c'è un pezzo che cambia». Il nome dentro le graffe deve tornare, uguale lettera per lettera, tra gli argomenti del def: è così che FastAPI li collega.
Nell'indirizzo è tutto testo. int dice a FastAPI di trasformare "3" nel numero 3 prima di chiamarti:
curl -s http://127.0.0.1:8000/stazioni/3
curl -s http://127.0.0.1:8000/stazioni/abc{"id":3,"nome":"Largo Lista","aperta":true}
{"detail":[{"type":"int_parsing","loc":["path","stazione_id"],"msg":"Input should be a valid integer, unable to parse string as an integer","input":"abc"}]}Con abc la tua funzione non parte nemmeno: risponde FastAPI, con un 422. Il loc dice dove ha trovato il guaio: "path", il percorso, e il nome, stazione_id.
La query: tutto il resto
@app.get("/viaggio")
def viaggio(da: int, a: int) -> dict:Nel decoratore non c'è niente tra graffe: da e a non sono nel percorso, quindi FastAPI li cerca nella query, dopo il ?. L'ordine nella query non conta: conta il nome.
curl -s "http://127.0.0.1:8000/viaggio?da=1&a=5"
curl -s "http://127.0.0.1:8000/viaggio?a=5&da=1"
curl -s "http://127.0.0.1:8000/viaggio?da=1"{"da":"Porta Codice","a":"Piazza Query","fermate":4,"minuti":12,"prezzo":2.2}
{"da":"Porta Codice","a":"Piazza Query","fermate":4,"minuti":12,"prezzo":2.2}
{"detail":[{"type":"missing","loc":["query","a"],"msg":"Field required","input":null}]}da: int e a: int non hanno un default: sono obbligatori. Manca a? 422, Field required («campo obbligatorio»), e il loc dice ["query","a"].
Facoltativa: = None. Se dai un default all'argomento, il client può non mandarlo. Il default più usato è None, «non me l'hai detto»:
@app.get("/stazioni")
def lista_stazioni(aperta: bool | None = None) -> list[Stazione]:
if aperta is None:
return list(stazioni.values()) # nessun filtro: tutte
...bool | None si legge «un vero o falso, oppure niente». Senza ?aperta=… la funzione parte lo stesso, con aperta che vale None, e la prima cosa che fa è chiederselo: if aperta is None:. = None e is None vanno sempre in coppia.
Un bool nella query si scrive true o false (vanno bene anche 1 e 0). si no:
curl -s "http://127.0.0.1:8000/stazioni?aperta=false"
curl -s "http://127.0.0.1:8000/stazioni?aperta=si"[{"id":6,"nome":"Vecchia Fiera","aperta":false}]
{"detail":[{"type":"bool_parsing","loc":["query","aperta"],"msg":"Input should be a valid boolean, unable to interpret input","input":"si"}]}Il corpo: uno stampo
Il corpo è il JSON che il client manda dopo gli header, nelle POST e nelle PUT. Nel def lo riconosci perché il tipo dell'argomento è uno stampo, una classe BaseModel (l'hai vista in fondo a Classi e oggetti: i campi con il loro tipo, e niente __init__). Ecco quello di InfoMenta, semplificato (quello vero ha qualche controllo in più: è il capitolo Pydantic):
class TrenoNuovo(BaseModel):
codice: str
tipo: str
vagoni: int
stazione_id: int
@app.post("/treni")
def nuovo_treno(dati: TrenoNuovo) -> Treno:
...FastAPI vede dati: TrenoNuovo, va a leggere il corpo, controlla campo per campo e crea l'oggetto. Dentro la funzione dati è già un TrenoNuovo: dati.codice, dati.vagoni, con il punto.
curl -s -X POST http://127.0.0.1:8000/treni \
-H "Content-Type: application/json" \
-d '{"codice": "M18", "tipo": "metro", "vagoni": 4, "stazione_id": 3}'
curl -s -X POST http://127.0.0.1:8000/treni \
-H "Content-Type: application/json" \
-d '{"codice": "M20", "tipo": "metro", "stazione_id": 3}'
curl -s -X POST http://127.0.0.1:8000/treni{"codice":"M18","tipo":"metro","vagoni":4,"stazione_id":3,"guasto":null,"id":7}
{"detail":[{"type":"missing","loc":["body","vagoni"],"msg":"Field required","input":{"codice":"M20","tipo":"metro","stazione_id":3}}]}
{"detail":[{"type":"missing","loc":["body"],"msg":"Field required","input":null}]}Nella prima risposta ci sono anche guasto, un campo facoltativo dello stampo vero, e l'id, che sceglie il server. Il secondo corpo non ha vagoni: ["body","vagoni"]. Il terzo non ha proprio il corpo: ["body"], e basta.
Il disegno.
Le tre righe fisse di ogni rotta
Tutte le rotte hanno la stessa forma. Tre righe fisse, poi dentro il lavoro:
@app.verbo("/percorso/{un_id}") 1. il verbo e il percorso
def nome_della_funzione(un_id: int, dati: Stampo) -> Risposta:
2. un argomento per ogni dato
3. dopo ->, la forma della risposta
il controllo: c'è quello che cerco?
il lavoro: leggo, calcolo, aggiungo, sostituisco, tolgo
return: quello che torna al clientNon tutte le rotte hanno tutto. Ecco i sei casi che ritroverai sempre, con i treni:
| Caso | La richiesta | La riga del def | Dove guarda |
|---|---|---|---|
| La lista | GET /treni | def lista_treni() -> list[Treno]: | da nessuna parte: nessun dato |
| Uno solo | GET /treni/5 | def leggi_treno(treno_id: int) -> Treno: | percorso |
| Con un filtro | GET /treni?tipo=tram | def lista_treni(tipo: str | None = None) -> list[Treno]: | query |
| Crea | POST /treni + corpo | def nuovo_treno(dati: TrenoNuovo) -> Treno: | corpo |
| Sostituisce | PUT /treni/5 + corpo | def sostituisci_treno(treno_id: int, dati: TrenoNuovo) -> Treno: | percorso e corpo |
| Toglie | DELETE /treni/5 | def togli_treno(treno_id: int) -> None: | percorso |
Dopo la freccia -> c'è la forma della risposta: dict un dizionario, Treno un treno, list[Treno] una lista di treni, None niente. Nella palestra di questo capitolo le rotte rispondono tutte con un dizionario: -> dict.
Cosa succede dentro, con il 404, il 201 e il 204, è il capitolo CRUD su un dizionario. Qui conta la forma.
Come lo vedi in /docs
Accendi il server e apri http://127.0.0.1:8000/docs. Ogni rotta, aperta, ha due riquadri:
- Parameters: i dati del percorso e della query. Sotto ogni nome c'è il tipo (
integer,string,boolean) e, tra parentesi, dove sta:(path)o(query). Gli obbligatori hanno la scritta rossa* required. - Request body: c'è solo se un argomento è uno stampo. Mostra un esempio di JSON, con i campi dello stampo.
È il modo più veloce per controllare che FastAPI abbia capito quello che volevi. Un id che doveva stare nel percorso e compare come (query)? Il nome tra graffe e quello nel def non coincidono. Niente Request body in una POST? L'argomento non è uno stampo.
Il 422 si legge dal loc
Ogni 422 di questo capitolo si capisce dal primo pezzo del loc:
Il loc comincia con | Il dato sbagliato o mancante sta | Un esempio vero |
|---|---|---|
"path" | nel percorso | /stazioni/abc → ["path","stazione_id"] |
"query" | nella query | /viaggio?da=1 → ["query","a"] |
"body" | nel corpo | un treno senza vagoni → ["body","vagoni"] |
Un 422 vuol dire anche un'altra cosa: la tua funzione non è mai partita. FastAPI ha fermato la richiesta prima. Nel terminale del server lo vedi così, senza nessun traceback:
INFO: 127.0.0.1:62873 - "GET /stazioni/abc HTTP/1.1" 422 Unprocessable EntityIl resto del 422 (type, msg, input), letto campo per campo, è nel capitolo Pydantic.
Adesso sai dove arriva ogni dato. Nel prossimo capitolo, Pydantic, guardi da vicino lo stampo: i limiti, i valori ammessi, il 422 letto tutto. Poi, in CRUD su un dizionario, le stesse righe del def salvano, cambiano e tolgono i dati davvero.
Ricorda
- Un nome tra graffe nel decoratore, lo stesso nome nel
def: percorso. - Un nome che non è nel percorso, con un tipo semplice: query. Con
= Noneè facoltativo, e dentro chiediis None. - Un nome che ha per tipo uno stampo: corpo, il JSON di POST e PUT.
intconverte il testo in numero; una parola al posto del numero è un 422, prima della tua funzione.- Il 422 dice dove guardare:
path,queryobody, nelloc.