Vai al contenuto
code-to-code

Apro l'indice…

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

HTTP e API8. Il contrattop. 244

Il contratto, le soluzioni

Le tabelle, le rotte, le trappole

Per ogni esercizio, sempre lo stesso ordine: la tabella delle rotte → in italiano → il codice → le trappole. Per il terzo, anche il passo per passo.

Il tuo contratto è diverso ma i test sono verdi? Probabilmente va bene: il nome delle funzioni e il nome tra graffe li scegli tu, e per qualche azione ci sono due strade giuste. Confronta il ragionamento, non le singole parole. E leggi comunque le trappole: alcune passano quasi tutti i test e si rompono su uno solo.

Le soluzioni complete

La stessa cartella, con il codice al posto di pass. Aprila dopo averci provato: i test sono gli stessi.

http-contratto-soluzioni.zip15 KB

Nel codice qui sotto ci sono solo le rotte: gli stampi e il canvas sono quelli del file, e non cambiano. Dentro ogni rotta c'è la stessa riga, il 501 del contratto.


1 · Gli estintori delle stazioni

La tabella.

AzioneRichiestaMando → RicevoCodiciLogin
1. Vedo tutti gli estintoriGET /estintoriniente → la lista degli estintori200no
2. Vedo un estintoreGET /estintori/{estintore_id}niente → l'estintore200, 404no
3. Registro un estintore nuovoPOST /estintoristazione, posizione, data del controllo → l'estintore con il suo id201, 422sì
4. Segno un controlloPUT /estintori/{estintore_id}tutti i campi, con la data nuova → l'estintore cambiato200, 404, 422sì
5. Tolgo un estintoreDELETE /estintori/{estintore_id}niente → niente204, 404sì

In italiano. Una cosa sola, gli estintori: una risorsa sola, /estintori. Vedere tutti è una GET sulla lista; vedere uno, una GET con l'id nel percorso. Registrare fa nascere un estintore: POST, con il 201. Il controllo cambia la data: l'estintore cambia, quindi PUT, con tutti i campi nel corpo. Togliere: DELETE, con il 204.

Python
# 1. vedo tutti gli estintori · login: no
@app.get("/estintori")
def lista_estintori() -> list[Estintore]:
    raise HTTPException(status_code=501, detail="Contratto: la rotta c'è, il codice arriva dopo")


# 2. vedo un estintore · login: no
@app.get("/estintori/{estintore_id}")
def leggi_estintore(estintore_id: int) -> Estintore:
    raise HTTPException(status_code=501, detail="Contratto: la rotta c'è, il codice arriva dopo")


# 3. registro un estintore nuovo · login: sì
@app.post("/estintori", status_code=status.HTTP_201_CREATED)
def nuovo_estintore(dati: EstintoreNuovo) -> Estintore:
    raise HTTPException(status_code=501, detail="Contratto: la rotta c'è, il codice arriva dopo")


# 4. segno un controllo · login: sì
@app.put("/estintori/{estintore_id}")
def sostituisci_estintore(estintore_id: int, dati: EstintoreNuovo) -> Estintore:
    raise HTTPException(status_code=501, detail="Contratto: la rotta c'è, il codice arriva dopo")


# 5. tolgo un estintore · login: sì
@app.delete("/estintori/{estintore_id}", status_code=status.HTTP_204_NO_CONTENT)
def togli_estintore(estintore_id: int) -> None:
    raise HTTPException(status_code=501, detail="Contratto: la rotta c'è, il codice arriva dopo")

Nella PUT lo stampo è EstintoreNuovo, senza id: l'id è già nel percorso, e mandarlo due volte vorrebbe dire poterlo mandare diverso.

Le trappole.

Il codice sbagliatoCosa succedeIl test rosso
@app.post("/estintori/{estintore_id}/controllo") per segnare un controlloIl verbo è finito nel percorso: «controllo» non è una cosa del canvas. E la PUT non c'ètest_4_il_controllo_e_una_put_con_l_id_e_il_corpo, test_6_le_cinque_regole_dei_percorsi
@app.get("/estintori") con estintore_id: int nel def, per l'azione 2L'id finisce nella query, e le rotte GET /estintori diventano due. Quando chiami risponde la prima, la lista; il contratto e /docs invece mostrano la seconda. Nessun errore, due bugietest_1_vedo_tutti_gli_estintori, test_2_un_estintore_con_l_id_nel_percorso
def leggi_estintore(id: int) sotto @app.get("/estintori/{estintore_id}")I due nomi sono diversi, e FastAPI non li collega: id diventa un parametro della query, obbligatorio. GET /estintori/3 risponderebbe 422test_6_le_cinque_regole_dei_percorsi
@app.post("/estintori") senza status_codeIl contratto promette un 200: chi usa l'API non sa che è nato qualcosatest_3_registrare_e_una_post_con_il_corpo_e_il_201
def nuovo_estintore(dati: Estintore)Lo stampo con l'id: il client dovrebbe inventarsi l'id, che invece sceglie il servertest_3_registrare_e_una_post_con_il_corpo_e_il_201

La seconda è la più subdola: Python non dice niente, il server parte, la lista risponde. Si vede solo leggendo il contratto, ed è per questo che i test lo leggono.


2 · Gli interventi dell'officina

La tabella.

AzioneRichiestaMando → RicevoCodiciLogin
1. Vedo gli interventi, anche solo quelli in uno statoGET /interventi?stato=aperto (il filtro può mancare)niente → la lista degli interventi200no
2. Vedo gli interventi di un trenoGET /treni/{treno_id}/interventiniente → la lista degli interventi del treno200, 404no
3. Apro un interventoPOST /interventitreno, lavoro, stato → l'intervento con il suo id201, 422sì
4. Chiudo un interventoPUT /interventi/{intervento_id}tutti i campi, con lo stato "chiuso" → l'intervento cambiato200, 404, 422sì
5. Cancello un interventoDELETE /interventi/{intervento_id}niente → niente204, 404sì

In italiano. Due cose nel canvas, ma i treni si guardano soltanto: compaiono in un percorso solo, quello della sotto-risorsa. Lo stato è una caratteristica dell'intervento, e può mancare: filtro, nella query, con = None. «La scheda di un treno, e se il treno non c'è 404»: la cosa di partenza deve esistere, quindi sotto-risorsa. Chiudere cambia lo stato: PUT.

Python
# 1. vedo gli interventi, anche solo quelli in uno stato · login: no
@app.get("/interventi")
def lista_interventi(stato: str | None = None) -> list[Intervento]:
    raise HTTPException(status_code=501, detail="Contratto: la rotta c'è, il codice arriva dopo")


# 2. gli interventi di un treno · login: no
@app.get("/treni/{treno_id}/interventi")
def interventi_del_treno(treno_id: int) -> list[Intervento]:
    raise HTTPException(status_code=501, detail="Contratto: la rotta c'è, il codice arriva dopo")


# 3. apro un intervento · login: sì
@app.post("/interventi", status_code=status.HTTP_201_CREATED)
def nuovo_intervento(dati: InterventoNuovo) -> Intervento:
    raise HTTPException(status_code=501, detail="Contratto: la rotta c'è, il codice arriva dopo")


# 4. chiudo un intervento · login: sì
@app.put("/interventi/{intervento_id}")
def sostituisci_intervento(intervento_id: int, dati: InterventoNuovo) -> Intervento:
    raise HTTPException(status_code=501, detail="Contratto: la rotta c'è, il codice arriva dopo")


# 5. cancello un intervento · login: sì
@app.delete("/interventi/{intervento_id}", status_code=status.HTTP_204_NO_CONTENT)
def togli_intervento(intervento_id: int) -> None:
    raise HTTPException(status_code=501, detail="Contratto: la rotta c'è, il codice arriva dopo")

Il treno da riparare, nella POST, non sta nel percorso: è già dentro InterventoNuovo, nel campo treno_id. Per questo la richiesta va a /interventi, e non a /treni/{treno_id}/interventi.

Le trappole.

Il codice sbagliatoCosa succedeIl test rosso
@app.get("/interventi/{stato}") con stato: strIl filtro nel percorso: diventa obbligatorio, e non c'è più una rotta per vederli tutti. Tra graffe c'è un testo, non un idtest_1_gli_interventi_con_il_filtro_dello_stato, test_6_le_cinque_regole_dei_percorsi
def lista_interventi(stato: str), senza = NoneIl filtro diventa obbligatorio: GET /interventi da solo risponderebbe 422, Field requiredtest_1_gli_interventi_con_il_filtro_dello_stato
treno_id: int | None = None aggiunto alla lista, e nessuna sotto-risorsaFunziona, ma per un treno che non esiste risponde 200 e []. Il canvas chiedeva il 404test_2_gli_interventi_di_un_treno_sono_una_sotto_risorsa
@app.post("/interventi/{intervento_id}/chiudi")Il verbo nel percorso, e la PUT non c'ètest_4_chiudere_un_intervento_e_una_put, test_6_le_cinque_regole_dei_percorsi

La terza non è un errore di sintassi e nemmeno di stile: è una scelta di contratto diversa da quella del canvas. Rileggi l'esempio D degli esercizi spiegati: [] e 404 dicono due cose diverse a chi usa l'API.


3 · Le visite guidate a Vecchia Fiera

La tabella.

AzioneRichiestaMando → RicevoCodiciLogin
1. Vedo le visite in programmaGET /visiteniente → la lista delle visite200no
2. Vedo una visitaGET /visite/{visita_id}niente → la visita200, 404no
3. Aggiungo una visitaPOST /visitegiorno, ora, posti → la visita con il suo id201, 422sì, solo Marta
4. Vedo chi ha prenotato una visitaGET /visite/{visita_id}/prenotazioniniente → la lista delle prenotazioni200, 404sì, solo Marta
5. Prenoto dei postiPOST /prenotazionivisita, nome, persone → la prenotazione con il suo id201, 404, 409, 422sì
6. Disdico una prenotazioneDELETE /prenotazioni/{prenotazione_id}niente → niente204, 404sì

Nella POST /prenotazioni c'è anche il 404: se visita_id è una visita che non c'è. Nella tabella va scritto; nel contratto in FastAPI, come nella teoria, mettiamo solo il 409.

In italiano. Due cose, due risorse: /visite e /prenotazioni. Le prime tre azioni parlano di visite, e sono le solite: la lista, una sola, una nuova. La quarta parte da una visita che deve esistere: sotto-risorsa. La quinta crea una prenotazione, con la visita nel corpo: POST /prenotazioni, con il 201 e il 409 dei posti esauriti. La sesta toglie una prenotazione, che ha il suo id: DELETE /prenotazioni/{prenotazione_id}.

Passo per passo.

AzioneDi quale cosa parla?Legge o scrive?Una o tante?La richiesta
1. Le visite in programmavisiteleggetanteGET /visite
2. Una visitavisiteleggeunaGET /visite/{visita_id}
3. Aggiungo una visitavisitescrive: nasceuna, nuovaPOST /visite, 201
4. Chi ha prenotatoprenotazioni, di una visita che deve esistereleggetanteGET /visite/{visita_id}/prenotazioni
5. Prenotoprenotazioniscrive: nasceuna, nuovaPOST /prenotazioni, 201 e 409
6. Disdicoprenotazioniscrive: sparisceunaDELETE /prenotazioni/{prenotazione_id}, 204
Python
# 1. vedo le visite in programma · login: no
@app.get("/visite")
def lista_visite() -> list[Visita]:
    raise HTTPException(status_code=501, detail="Contratto: la rotta c'è, il codice arriva dopo")


# 2. vedo una visita · login: no
@app.get("/visite/{visita_id}")
def leggi_visita(visita_id: int) -> Visita:
    raise HTTPException(status_code=501, detail="Contratto: la rotta c'è, il codice arriva dopo")


# 3. aggiungo una visita al programma · login: sì, solo Marta
@app.post("/visite", status_code=status.HTTP_201_CREATED)
def nuova_visita(dati: VisitaNuova) -> Visita:
    raise HTTPException(status_code=501, detail="Contratto: la rotta c'è, il codice arriva dopo")


# 4. vedo chi ha prenotato una visita · login: sì, solo Marta
@app.get("/visite/{visita_id}/prenotazioni")
def prenotazioni_della_visita(visita_id: int) -> list[Prenotazione]:
    raise HTTPException(status_code=501, detail="Contratto: la rotta c'è, il codice arriva dopo")


# 5. prenoto dei posti per una visita · login: sì
@app.post(
    "/prenotazioni",
    status_code=status.HTTP_201_CREATED,
    responses={409: {"description": "Posti esauriti"}},
)
def nuova_prenotazione(dati: PrenotazioneNuova) -> Prenotazione:
    raise HTTPException(status_code=501, detail="Contratto: la rotta c'è, il codice arriva dopo")


# 6. disdico una prenotazione · login: sì
@app.delete("/prenotazioni/{prenotazione_id}", status_code=status.HTTP_204_NO_CONTENT)
def togli_prenotazione(prenotazione_id: int) -> None:
    raise HTTPException(status_code=501, detail="Contratto: la rotta c'è, il codice arriva dopo")

Anche POST /visite/{visita_id}/prenotazioni, con la visita nel percorso, sarebbe un contratto sensato. Qui però lo stampo PrenotazioneNuova ha già visita_id: la visita arriva nel corpo, e metterla anche nel percorso vorrebbe dire scriverla due volte. Il test vuole POST /prenotazioni.

Le trappole.

Il codice sbagliatoCosa succedeIl test rosso
La POST /prenotazioni senza responses=Il 409 non è nel contratto: chi scrive l'app non sa che i posti possono finire, e non prepara il messaggio «posti esauriti»test_5_prenotare_e_una_post_con_il_201_e_il_409
"/visite/{visita_id}/prenota" nel decoratore della prenotazioneIl verbo nel percorso: «prenota» non è una cosa del canvas. E POST /prenotazioni non c'ètest_5_prenotare_e_una_post_con_il_201_e_il_409, test_7_le_cinque_regole_dei_percorsi
@app.get("/prenotazioni") con visita_id: int, per l'azione 4Un filtro al posto della sotto-risorsa: una visita che non c'è darebbe una lista vuota invece del 404test_4_le_prenotazioni_di_una_visita_sono_una_sotto_risorsa
@app.get("/visita/{visita_id}")Il singolare: /visita e /visite sono due risorse diverse, per chi usa l'APItest_2_una_visita_con_l_id_nel_percorso, test_7_le_cinque_regole_dei_percorsi

E adesso il tuo

Il canvas del tuo progetto ha i riquadri 6, 7 e 8. Fai lo stesso giro: una risorsa per cosa, una richiesta per azione, la tabella da 5 a 10 righe in un ROTTE.md. Poi scambiala con un compagno, che risponde sì, no o «non so» a tre domande:

  1. Per ogni funzione del riquadro 4 c'è almeno una richiesta?
  2. Ogni percorso è fatto di nomi al plurale, e l'azione la dice il verbo?
  3. Guardando solo la tabella, saprei cosa mandare e cosa aspettarmi indietro?