Vai al contenuto
code-to-code

Apro l'indice…

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

HTTP e API5. La forma della chiamatap. 112

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 corpo

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

Python
@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 decoratorenel percorsostazione_id: int, con "/stazioni/{stazione_id}"
un nome che non è nel percorso, con un tipo semplice (int, str, bool)nella queryda: int e a: int
un nome che ha per tipo uno stampo (una classe BaseModel)nel corpodati: 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

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

Terminale
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

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

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

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

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

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

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

dati = TrenoNuovo(codice="M18", tipo="metro", vagoni=4, stazione_id=3)datiTrenoNuovocodice"M18"tipo"metro"vagoni4stazione_id3
Dentro la funzione, dopo la prima POST

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 client

Non tutte le rotte hanno tutto. Ecco i sei casi che ritroverai sempre, con i treni:

CasoLa richiestaLa riga del defDove guarda
La listaGET /trenidef lista_treni() -> list[Treno]:da nessuna parte: nessun dato
Uno soloGET /treni/5def leggi_treno(treno_id: int) -> Treno:percorso
Con un filtroGET /treni?tipo=tramdef lista_treni(tipo: str | None = None) -> list[Treno]:query
CreaPOST /treni + corpodef nuovo_treno(dati: TrenoNuovo) -> Treno:corpo
SostituiscePUT /treni/5 + corpodef sostituisci_treno(treno_id: int, dati: TrenoNuovo) -> Treno:percorso e corpo
ToglieDELETE /treni/5def 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 conIl dato sbagliato o mancante staUn esempio vero
"path"nel percorso/stazioni/abc → ["path","stazione_id"]
"query"nella query/viaggio?da=1 → ["query","a"]
"body"nel corpoun 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 Entity

Il 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 chiedi is None.
  • Un nome che ha per tipo uno stampo: corpo, il JSON di POST e PUT.
  • int converte il testo in numero; una parola al posto del numero è un 422, prima della tua funzione.
  • Il 422 dice dove guardare: path, query o body, nel loc.