Vai al contenuto
code-to-code

Apro l'indice…

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

HTTP e API5. La forma della chiamatap. 118

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:

  1. Prevedi: leggi il codice e scrivi su un foglio la richiesta, o la risposta. Prima di aprire la soluzione.
  2. In italiano: cosa fa la rotta, a parole.
  3. Passo per passo: dove guarda FastAPI, un argomento alla volta.
  4. 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):

Terminale
fastapi dev bordo.py

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

Python
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.
Terminale
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 guardaNella richiestaNella funzione vale
numero: intsì, {numero}nel percorso/carrozze/2/posti2
occupati: intnonella query?occupati=4545

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 OK

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

Terminale
fastapi dev deposito.py

Passo per passo. Si smonta l'indirizzo, pezzo per pezzo:

Pezzo dell'indirizzoFisso o cambia?Dove vaNel codice
/lavaggio/fissonel decoratore, così com'è"/lavaggio/…"
M14cambia: M16, T05…nel percorso, tra graffe{codice} nel decoratore, codice: str nel def
?vagoni=3cambianella queryvagoni: int nel def, senza graffe

codice è str perché M14 è un testo. vagoni è int, così puoi moltiplicarlo. Proviamo:

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

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

Terminale
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: ritardo vale None, l'if è vero, esce il primo return.
  • La seconda ha tutti e due i dati: l'if è falso, esce il secondo return.
  • 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.

inizio GET /annuncio?fermata=… se manca fermata sì: errore 422 Lo dice FastAPI se ritardo is None sì: restituisci testo con la sola fermata restituisci testo con fermata e ritardoGET /annuncio?fermata=…manca fermata422 Lo dice FastAPIritardo is Nonerestituisci testo con lasola fermatarestituisci testo confermata e ritardonosìnosì
L'annuncio, con o senza ritardo

Passo per passo.

La richiestafermataritardoCosa succede
?fermata=Largo%20Lista"Largo Lista"Noneritardo is None: primo return
?fermata=Largo%20Lista&ritardo=4"Largo Lista"4secondo return
?ritardo=4manca4422: 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):

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

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

inizio POST /controlli passo legge il JSON del corpo se manca un campo o non è un numero sì: errore 422 La funzione non parte passo crea Controllo(...) passo chiama nuovo_controllo(dati) restituisci 200 e carrozza, in_regolaPOST /controllilegge il JSON del corpomanca un campo o nonè un numero422 La funzione non partecrea Controllo(...)chiama nuovo_controllo(dati)restituisci 200 e carrozza,in_regolanosì
Cosa fa FastAPI prima della funzione

Passo per passo. Cosa fa FastAPI prima di chiamare nuovo_controllo:

  1. Legge il def: dati ha per tipo Controllo, che è uno stampo. Quindi guarda nel corpo.
  2. Legge il JSON del corpo. Per questo serve l'header Content-Type: application/json.
  3. Controlla i campi: ci sono tutti e tre, e sono numeri.
  4. Crea l'oggetto: Controllo(carrozza=2, controllati=40, senza_biglietto=3).
  5. Chiama la tua funzione con quell'oggetto in dati. Dentro, i campi si leggono con il punto: dati.controllati vale 40.

Il disegno.

dati = Controllo(carrozza=2, controllati=40, senza_biglietto=3)datiControllocarrozza2controllati40senza_biglietto3
L'oggetto che riceve la funzione

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.

Python
@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,
    }
Terminale
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?

Terminale
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}}]}
  1. ["path","numero"]: nel percorso, al posto del numero della carrozza, c'è due.
  2. ["query","occupati"]: nella query manca occupati, che è obbligatorio.
  3. ["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.

locDoveCosaCome si sistema
["path","numero"]percorsonumero, che deve essere un int/carrozze/2/posti
["query","occupati"]queryoccupati, obbligatorio?occupati=45
["body","senza_biglietto"]corpoil campo senza_bigliettoaggiungerlo 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 Entity

Un quarto sbaglio, il più comune di tutti: il JSON giusto, ma senza l'header Content-Type.

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