La forma della chiamata, esercizi spiegati
Cinque esempi, dalla richiesta al def e ritorno
- 25 minuti di lettura
Cinque esempi, dal più semplice. Ognuno ha lo stesso ritmo:
- Prevedi: leggi il codice e scrivi su un foglio la richiesta, o la risposta. Prima di aprire la soluzione.
- In italiano: cosa fa la rotta, a parole.
- Passo per passo: dove guarda FastAPI, un argomento alla volta.
- Cosa portiamo a casa: la cosa da ricordare.
Ogni esempio è una piccola API che puoi accendere. Copia il codice in un file nella cartella dello zip, accanto a palestra/ (per esempio ~/corso/http-forma-della-chiamata/bordo.py). Poi, nel primo terminale (venv acceso):
fastapi dev bordo.pye i comandi curl nel secondo terminale. Ogni volta che salvi il file, il server riparte da solo.
A · Quanti posti liberi? Dal def alla richiesta
Lucia Ferri, capotreno dell'M12, ha sul tablet di bordo una piccola API. Ogni carrozza ha 60 posti.
from fastapi import FastAPI
app = FastAPI(title="Il tablet di bordo")
POSTI_PER_CARROZZA = 60
@app.get("/carrozze/{numero}/posti")
def posti_liberi(numero: int, occupati: int) -> dict:
return {"carrozza": numero, "liberi": POSTI_PER_CARROZZA - occupati}Lucia è nella carrozza 2 e ha contato 45 persone sedute. Prevedi: che comando curl scrive per sapere quanti posti sono liberi? E cosa risponde l'API?
Prevedi Scrivi su un foglio cosa ti aspetti, poi apri.
curl -s "http://127.0.0.1:8000/carrozze/2/posti?occupati=45"{"carrozza":2,"liberi":15}L'indirizzo va tra virgolette perché c'è il ?: senza, il terminale potrebbe leggerlo a modo suo.
In italiano. La rotta riceve due numeri: la carrozza, nel percorso, e i posti occupati, nella query. Risponde con i posti liberi: 60 meno gli occupati.
Passo per passo. Per scrivere la richiesta si legge il def un argomento alla volta, e per ognuno si fa la domanda della teoria: è tra graffe?
| Argomento | È tra graffe nel decoratore? | FastAPI guarda | Nella richiesta | Nella funzione vale |
|---|---|---|---|---|
numero: int | sì, {numero} | nel percorso | /carrozze/2/posti | 2 |
occupati: int | no | nella query | ?occupati=45 | 45 |
Nel terminale del server compare la stessa richiesta, vista da lì:
INFO: 127.0.0.1:62892 - "GET /carrozze/2/posti?occupati=45 HTTP/1.1" 200 OKCosa portiamo a casa. Il decoratore ti dà lo scheletro dell'indirizzo, con i buchi tra graffe. Gli argomenti del def che non sono nei buchi vanno dopo il ?.
B · Il lavaggio dei treni: dalla richiesta al def
Al deposito, Ernesto Pozzi vuole sapere quanto ci vuole a lavare un treno: dieci minuti a vagone. Ti scrive la richiesta e la risposta che vuole:
GET /lavaggio/M14?vagoni=3 -> {"treno": "M14", "minuti": 30}Prevedi: scrivi il decoratore, la riga del def e il return.
Prevedi Scrivi su un foglio cosa ti aspetti, poi apri.
from fastapi import FastAPI
app = FastAPI(title="Il deposito")
MINUTI_PER_VAGONE = 10
@app.get("/lavaggio/{codice}")
def lavaggio(codice: str, vagoni: int) -> dict:
return {"treno": codice, "minuti": vagoni * MINUTI_PER_VAGONE}Il nome tra graffe lo scegli tu (codice, treno…): basta che sia lo stesso nel def.
In italiano. Il codice del treno cambia da richiesta a richiesta, quindi è un pezzo variabile del percorso. I vagoni arrivano dopo il ?, quindi sono una query.
Per provarla, salvala in un file nuovo, deposito.py, accanto a bordo.py. Nel primo terminale spegni il server di prima con Ctrl+C (la porta 8000 è una sola) e accendi questo:
fastapi dev deposito.pyPasso per passo. Si smonta l'indirizzo, pezzo per pezzo:
| Pezzo dell'indirizzo | Fisso o cambia? | Dove va | Nel codice |
|---|---|---|---|
/lavaggio/ | fisso | nel decoratore, così com'è | "/lavaggio/…" |
M14 | cambia: M16, T05… | nel percorso, tra graffe | {codice} nel decoratore, codice: str nel def |
?vagoni=3 | cambia | nella query | vagoni: int nel def, senza graffe |
codice è str perché M14 è un testo. vagoni è int, così puoi moltiplicarlo. Proviamo:
curl -s "http://127.0.0.1:8000/lavaggio/M14?vagoni=3"
curl -s "http://127.0.0.1:8000/lavaggio/M16?vagoni=6"
curl -s http://127.0.0.1:8000/lavaggio/M14{"treno":"M14","minuti":30}
{"treno":"M16","minuti":60}
{"detail":[{"type":"missing","loc":["query","vagoni"],"msg":"Field required","input":null}]}Cosa portiamo a casa. Quello che cambia nel percorso va tra graffe, con lo stesso nome nel def. Quello che sta dopo il ? va nel def senza graffe.
C · L'annuncio, con o senza ritardo: la query facoltativa
Lucia aggiunge al tablet l'annuncio della prossima fermata. Il ritardo, se c'è, va detto; se non c'è, no. Torna a bordo.py (nel primo terminale: Ctrl+C, poi fastapi dev bordo.py) e aggiungi in fondo questa rotta:
@app.get("/annuncio")
def annuncio(fermata: str, ritardo: int | None = None) -> dict:
if ritardo is None:
return {"testo": f"Prossima fermata: {fermata}"}
return {"testo": f"Prossima fermata: {fermata}. Siamo in ritardo di {ritardo} minuti"}Prevedi cosa rispondono queste tre richieste. (%20 è lo spazio, scritto dentro un indirizzo: lo hai visto nel viaggio di una richiesta.)
curl -s "http://127.0.0.1:8000/annuncio?fermata=Largo%20Lista"
curl -s "http://127.0.0.1:8000/annuncio?fermata=Largo%20Lista&ritardo=4"
curl -s "http://127.0.0.1:8000/annuncio?ritardo=4"Prevedi Scrivi su un foglio cosa ti aspetti, poi apri.
{"testo":"Prossima fermata: Largo Lista"}
{"testo":"Prossima fermata: Largo Lista. Siamo in ritardo di 4 minuti"}
{"detail":[{"type":"missing","loc":["query","fermata"],"msg":"Field required","input":null}]}- La prima non ha il ritardo:
ritardovaleNone, l'ifè vero, esce il primoreturn. - La seconda ha tutti e due i dati: l'
ifè falso, esce il secondoreturn. - La terza non ha la fermata, che non ha un default: è obbligatoria. Risponde FastAPI, 422.
In italiano. La fermata serve sempre. Il ritardo è facoltativo: se non arriva, vale None e l'annuncio non lo nomina.
Il disegno.
Passo per passo.
| La richiesta | fermata | ritardo | Cosa succede |
|---|---|---|---|
?fermata=Largo%20Lista | "Largo Lista" | None | ritardo is None: primo return |
?fermata=Largo%20Lista&ritardo=4 | "Largo Lista" | 4 | secondo return |
?ritardo=4 | manca | 4 | 422: la funzione non parte |
FastAPI ha già trasformato %20 in uno spazio: nella funzione fermata vale "Largo Lista".
Due modi di sbagliarla, provati davvero.
Senza = None (ritardo: int): il ritardo diventa obbligatorio, e l'annuncio senza ritardo non passa più.
{"detail":[{"type":"missing","loc":["query","ritardo"],"msg":"Field required","input":null}]}Senza l'if (solo il secondo return): nessun errore, ma il treno annuncia una cosa strana.
{"testo":"Prossima fermata: Largo Lista. Siamo in ritardo di None minuti"}Cosa portiamo a casa. = None nel def e if … is None: dentro la funzione si scrivono sempre insieme.
D · Il controllo dei biglietti: il corpo
A fine giro, Lucia manda dal tablet il riepilogo di una carrozza: quanti biglietti ha controllato, quanti passeggeri erano senza. Sono tre dati che viaggiano insieme, in un JSON. Aggiungi in bordo.py lo stampo e la rotta (e from pydantic import BaseModel in cima):
class Controllo(BaseModel):
carrozza: int
controllati: int
senza_biglietto: int
@app.post("/controlli")
def nuovo_controllo(dati: Controllo) -> dict:
return {"carrozza": dati.carrozza, "in_regola": dati.controllati - dati.senza_biglietto}Prevedi la risposta:
curl -s -X POST http://127.0.0.1:8000/controlli \
-H "Content-Type: application/json" \
-d '{"carrozza": 2, "controllati": 40, "senza_biglietto": 3}'Prevedi Scrivi su un foglio cosa ti aspetti, poi apri.
{"carrozza":2,"in_regola":37}Risponde 200, non 201: questa rotta non salva niente, fa solo un conto. Salvare è il capitolo CRUD su un dizionario.
In italiano. La rotta riceve un controllo intero, nel corpo, e risponde con i passeggeri in regola.
Il disegno.
Passo per passo. Cosa fa FastAPI prima di chiamare nuovo_controllo:
- Legge il
def:datiha per tipoControllo, che è uno stampo. Quindi guarda nel corpo. - Legge il JSON del corpo. Per questo serve l'header
Content-Type: application/json. - Controlla i campi: ci sono tutti e tre, e sono numeri.
- Crea l'oggetto:
Controllo(carrozza=2, controllati=40, senza_biglietto=3). - Chiama la tua funzione con quell'oggetto in
dati. Dentro, i campi si leggono con il punto:dati.controllativale40.
Il disegno.
E con l'id? Lucia ha sbagliato a contare il controllo numero 7 e lo corregge. L'id va nel percorso, i dati nel corpo: è la forma di ogni PUT.
@app.put("/controlli/{controllo_id}")
def correggi_controllo(controllo_id: int, dati: Controllo) -> dict:
return {
"id": controllo_id,
"carrozza": dati.carrozza,
"in_regola": dati.controllati - dati.senza_biglietto,
}curl -s -X PUT http://127.0.0.1:8000/controlli/7 \
-H "Content-Type: application/json" \
-d '{"carrozza": 2, "controllati": 40, "senza_biglietto": 1}'{"id":7,"carrozza":2,"in_regola":39}Due argomenti, due posti: controllo_id è tra graffe (percorso), dati è uno stampo (corpo).
Cosa portiamo a casa. I dati che arrivano insieme, in un JSON, vanno in uno stampo: un argomento solo. L'id, se c'è, sta nel percorso, fuori dallo stampo.
E · Il 422 ti dice dove guardare
Con bordo.py acceso, Lucia sbaglia tre richieste in tre modi diversi. Prevedi, per ognuna: FastAPI dove ha cercato il dato che non va (percorso, query o corpo)? E quale nome?
curl -s "http://127.0.0.1:8000/carrozze/due/posti?occupati=45"
curl -s http://127.0.0.1:8000/carrozze/2/posti
curl -s -X POST http://127.0.0.1:8000/controlli \
-H "Content-Type: application/json" \
-d '{"carrozza": 2, "controllati": 40}'Prevedi Scrivi su un foglio cosa ti aspetti, poi apri.
{"detail":[{"type":"int_parsing","loc":["path","numero"],"msg":"Input should be a valid integer, unable to parse string as an integer","input":"due"}]}
{"detail":[{"type":"missing","loc":["query","occupati"],"msg":"Field required","input":null}]}
{"detail":[{"type":"missing","loc":["body","senza_biglietto"],"msg":"Field required","input":{"carrozza":2,"controllati":40}}]}["path","numero"]: nel percorso, al posto del numero della carrozza, c'èdue.["query","occupati"]: nella query mancaoccupati, che è obbligatorio.["body","senza_biglietto"]: nel corpo manca un campo dello stampo.
Passo per passo. Il loc è una lista di due pezzi: il primo dice dove, il secondo cosa.
loc | Dove | Cosa | Come si sistema |
|---|---|---|---|
["path","numero"] | percorso | numero, che deve essere un int | /carrozze/2/posti |
["query","occupati"] | query | occupati, obbligatorio | ?occupati=45 |
["body","senza_biglietto"] | corpo | il campo senza_biglietto | aggiungerlo al JSON |
Nel terminale del server le tre richieste sono tre righe con il 422, e nessun traceback: la funzione non è mai partita.
INFO: 127.0.0.1:62898 - "GET /carrozze/due/posti?occupati=45 HTTP/1.1" 422 Unprocessable Entity
INFO: 127.0.0.1:62899 - "GET /carrozze/2/posti HTTP/1.1" 422 Unprocessable Entity
INFO: 127.0.0.1:62900 - "POST /controlli HTTP/1.1" 422 Unprocessable EntityUn quarto sbaglio, il più comune di tutti: il JSON giusto, ma senza l'header Content-Type.
curl -s -X POST http://127.0.0.1:8000/controlli \
-d '{"carrozza": 2, "controllati": 40, "senza_biglietto": 3}'{"detail":[{"type":"model_attributes_type","loc":["body"],"msg":"Input should be a valid dictionary or object to extract fields from","input":"{\"carrozza\": 2, \"controllati\": 40, \"senza_biglietto\": 3}"}]}["body"], senza un nome di campo: il problema è il corpo intero. Senza l'header, curl lo manda come un modulo, e FastAPI riceve un testo invece di un dizionario JSON.
Cosa portiamo a casa. Davanti a un 422 non si rilegge tutto il codice: si legge il loc. path, query o body ti dice in quale dei tre posti guardare.
Pronto? Lo sportello di Porta Codice ti aspetta nella palestra: otto rotte da scrivere, una cosa nuova per rotta, con i test.