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.
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.
| Azione | Richiesta | Mando → Ricevo | Codici | Login |
|---|---|---|---|---|
| 1. Vedo tutti gli estintori | GET /estintori | niente → la lista degli estintori | 200 | no |
| 2. Vedo un estintore | GET /estintori/{estintore_id} | niente → l'estintore | 200, 404 | no |
| 3. Registro un estintore nuovo | POST /estintori | stazione, posizione, data del controllo → l'estintore con il suo id | 201, 422 | sì |
| 4. Segno un controllo | PUT /estintori/{estintore_id} | tutti i campi, con la data nuova → l'estintore cambiato | 200, 404, 422 | sì |
| 5. Tolgo un estintore | DELETE /estintori/{estintore_id} | niente → niente | 204, 404 | sì |
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.
# 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 sbagliato | Cosa succede | Il test rosso |
|---|---|---|
@app.post("/estintori/{estintore_id}/controllo") per segnare un controllo | Il 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 2 | L'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 bugie | test_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 422 | test_6_le_cinque_regole_dei_percorsi |
@app.post("/estintori") senza status_code | Il contratto promette un 200: chi usa l'API non sa che è nato qualcosa | test_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 server | test_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.
| Azione | Richiesta | Mando → Ricevo | Codici | Login |
|---|---|---|---|---|
| 1. Vedo gli interventi, anche solo quelli in uno stato | GET /interventi?stato=aperto (il filtro può mancare) | niente → la lista degli interventi | 200 | no |
| 2. Vedo gli interventi di un treno | GET /treni/{treno_id}/interventi | niente → la lista degli interventi del treno | 200, 404 | no |
| 3. Apro un intervento | POST /interventi | treno, lavoro, stato → l'intervento con il suo id | 201, 422 | sì |
| 4. Chiudo un intervento | PUT /interventi/{intervento_id} | tutti i campi, con lo stato "chiuso" → l'intervento cambiato | 200, 404, 422 | sì |
| 5. Cancello un intervento | DELETE /interventi/{intervento_id} | niente → niente | 204, 404 | sì |
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.
# 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 sbagliato | Cosa succede | Il test rosso |
|---|---|---|
@app.get("/interventi/{stato}") con stato: str | Il filtro nel percorso: diventa obbligatorio, e non c'è più una rotta per vederli tutti. Tra graffe c'è un testo, non un id | test_1_gli_interventi_con_il_filtro_dello_stato, test_6_le_cinque_regole_dei_percorsi |
def lista_interventi(stato: str), senza = None | Il filtro diventa obbligatorio: GET /interventi da solo risponderebbe 422, Field required | test_1_gli_interventi_con_il_filtro_dello_stato |
treno_id: int | None = None aggiunto alla lista, e nessuna sotto-risorsa | Funziona, ma per un treno che non esiste risponde 200 e []. Il canvas chiedeva il 404 | test_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.
| Azione | Richiesta | Mando → Ricevo | Codici | Login |
|---|---|---|---|---|
| 1. Vedo le visite in programma | GET /visite | niente → la lista delle visite | 200 | no |
| 2. Vedo una visita | GET /visite/{visita_id} | niente → la visita | 200, 404 | no |
| 3. Aggiungo una visita | POST /visite | giorno, ora, posti → la visita con il suo id | 201, 422 | sì, solo Marta |
| 4. Vedo chi ha prenotato una visita | GET /visite/{visita_id}/prenotazioni | niente → la lista delle prenotazioni | 200, 404 | sì, solo Marta |
| 5. Prenoto dei posti | POST /prenotazioni | visita, nome, persone → la prenotazione con il suo id | 201, 404, 409, 422 | sì |
| 6. Disdico una prenotazione | DELETE /prenotazioni/{prenotazione_id} | niente → niente | 204, 404 | sì |
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.
| Azione | Di quale cosa parla? | Legge o scrive? | Una o tante? | La richiesta |
|---|---|---|---|---|
| 1. Le visite in programma | visite | legge | tante | GET /visite |
| 2. Una visita | visite | legge | una | GET /visite/{visita_id} |
| 3. Aggiungo una visita | visite | scrive: nasce | una, nuova | POST /visite, 201 |
| 4. Chi ha prenotato | prenotazioni, di una visita che deve esistere | legge | tante | GET /visite/{visita_id}/prenotazioni |
| 5. Prenoto | prenotazioni | scrive: nasce | una, nuova | POST /prenotazioni, 201 e 409 |
| 6. Disdico | prenotazioni | scrive: sparisce | una | DELETE /prenotazioni/{prenotazione_id}, 204 |
# 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 sbagliato | Cosa succede | Il 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 prenotazione | Il 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 4 | Un filtro al posto della sotto-risorsa: una visita che non c'è darebbe una lista vuota invece del 404 | test_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'API | test_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:
- Per ogni funzione del riquadro 4 c'è almeno una richiesta?
- Ogni percorso è fatto di nomi al plurale, e l'azione la dice il verbo?
- Guardando solo la tabella, saprei cosa mandare e cosa aspettarmi indietro?