Vai al contenuto
code-to-code

Apro l'indice…

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

HTTP e API8. Il contrattop. 240

Il contratto, la palestra

Tre servizi, tre contratti, con i test

  • 60–90 minuti di lavoro

Tre servizi nuovi della Linea Menta, dal ★ al ★★★. Ognuno ha il suo canvas già riempito, in un commento in cima al file, e gli stampi già scritti: il contratto lo scrivi tu. Prima la tabella delle rotte, poi le rotte in FastAPI, con il 501 dentro. I test leggono il contratto: quando è tutto verde, hai finito.

Gli esercizi da scaricare

Una cartella con i file da completare e i test già pronti. Come si usa: la guida in cinque passi.

http-contratto.zip14 KB

Prima di iniziare

Scompatta lo zip e segui il README.md che c'è dentro: venv, pip install -r requirements.txt, code .. Se è la prima volta, la pagina Come si usa un esercizio lo fa con te, un comando alla volta.

Ogni esercizio, sempre gli stessi cinque passi:

  1. Apri il file in palestra/. In alto: la storia, cosa fai, come provi. Sotto: gli stampi e il canvas.
  2. Riempi la sua tabella in ROTTE.md, nella cartella dello zip: una riga per azione. Su carta va bene uguale. I test non la guardano, ma è lì che si pensa.
  3. Sotto il canvas, una rotta per azione: il decoratore, la riga del def, e dentro solo la riga del contratto, raise HTTPException(status_code=501, …).
  4. pytest palestra/test_<nome>.py -v. Rosso? L'ultima riga del messaggio dice quale rotta manca o cosa non torna.
  5. Tutto verde? fastapi dev palestra/<nome>.py e apri http://127.0.0.1:8000/docs: è il tuo contratto, come lo vedrà chi usa l'API.
#EsercizioCosa c'è di nuovoDifficoltà
1Gli estintori delle stazioniuna risorsa, i quattro verbi★
2Gli interventi dell'officinaun filtro e una sotto-risorsa★★
3Le visite guidate a Vecchia Fieradue risorse collegate, e il 409 nel contratto★★★

In ogni file di test, l'ultimo test è quello delle cinque regole dei percorsi: controlla tutte le rotte del file insieme. Se diventa rosso, il messaggio dice quale rotta e quale pezzo del percorso.


1 · Gli estintori delle stazioni ★

palestra/estintori.py

Nadia Russo, la guardia giurata, ogni mese controlla gli estintori di tutte le stazioni e li segna su un quaderno. Vuole un'API. Una cosa sola, cinque azioni, e la prima è già scritta: è l'esempio.

Riquadro 6 · le cose:    gli estintori → /estintori
Riquadro 7 · le azioni:
  1. vedo tutti gli estintori           (già fatta: l'esempio)
  2. vedo un estintore
  3. registro un estintore nuovo
  4. segno un controllo: cambia la data dell'ultimo controllo
  5. tolgo un estintore (è scaduto e l'hanno portato via)

Gli stampi: EstintoreNuovo (stazione, posizione, data dell'ultimo controllo: quello che manda il client, senza id) ed Estintore (gli stessi campi più l'id: quello che torna indietro).

Come provi: pytest palestra/test_estintori.py -v

Lanciato subito, prima di scrivere niente:

palestra/test_estintori.py::test_1_vedo_tutti_gli_estintori PASSED                           [ 16%]
palestra/test_estintori.py::test_2_un_estintore_con_l_id_nel_percorso FAILED                 [ 33%]
palestra/test_estintori.py::test_3_registrare_e_una_post_con_il_corpo_e_il_201 FAILED        [ 50%]
palestra/test_estintori.py::test_4_il_controllo_e_una_put_con_l_id_e_il_corpo FAILED         [ 66%]
palestra/test_estintori.py::test_5_togliere_e_una_delete_con_il_204 FAILED                   [ 83%]
palestra/test_estintori.py::test_6_le_cinque_regole_dei_percorsi PASSED                      [100%]
…
=================================== 4 failed, 2 passed in 0.15s ====================================

I due verdi sono l'esempio e le regole: con la sola rotta dell'esempio, le regole sono rispettate. Il test delle regole resta verde solo se anche le tue rotte le rispettano.

Aiutino 1
Per ogni azione: legge o scrive? Parla di un estintore o di tutti? È la tabella «passo per passo» dell'esempio B degli esercizi spiegati.
Aiutino 2
«Segno un controllo» cambia l'estintore: è una PUT su /estintori/{estintore_id}, con tutti i campi nel corpo. Niente /controllo nel percorso.
Aiutino 3
Nella POST: status_code=status.HTTP_201_CREATED nel decoratore e dati: EstintoreNuovo nel def. Nella DELETE: status_code=status.HTTP_204_NO_CONTENT e -> None.

2 · Gli interventi dell'officina ★★

palestra/interventi.py

Al deposito, Ivo Brambati segna su una lavagna i lavori da fare sui treni: le porte del T09, i freni dell'M14. Vuole un'API anche per questo. Nel canvas ci sono due cose, ma una sola si crea e si cancella: i treni ci sono già, qui si guardano soltanto.

Riquadro 6 · le cose:    gli interventi → /interventi
                         i treni → /treni (ci sono già: si guardano soltanto)
Riquadro 7 · le azioni:
  1. vedo gli interventi, anche solo quelli in uno stato (solo gli aperti, o solo i chiusi)
  2. apro la scheda di un treno e vedo i suoi interventi (se il treno non c'è: 404)
  3. apro un intervento nuovo
  4. chiudo un intervento: il lavoro è fatto, lo stato diventa "chiuso"
  5. cancello un intervento aperto per sbaglio

Gli stampi: InterventoNuovo (il treno, il lavoro, lo stato) e Intervento (con l'id).

Come provi: pytest palestra/test_interventi.py -v

Aiutino 1
Lo stato è un filtro: restringe l'elenco, e può mancare. Va nella query, facoltativo: stato: str | None = None.
Aiutino 2
«La scheda di un treno, con i suoi interventi; se il treno non c'è, 404»: la cosa di partenza deve esistere. È una sotto-risorsa: il percorso parte da /treni. Rileggi «Filtro o sotto-risorsa?» nella teoria.
Aiutino 3
Chiudere un intervento cambia il suo stato: PUT /interventi/{intervento_id}, con tutto l'intervento nel corpo e lo stato nuovo. Non /chiudi.

3 · Le visite guidate a Vecchia Fiera ★★★

palestra/visite.py

Vecchia Fiera è chiusa al pubblico da vent'anni, ma tutti la vogliono vedere. Marta Villa organizza le visite guidate: pochi posti, e si prenota. Rosa Bellini, per esempio, prenota per tutto il gruppo della sua agenzia. Due cose, collegate: ogni prenotazione è per una visita.

Riquadro 6 · le cose:    le visite → /visite
                         le prenotazioni → /prenotazioni (ognuna è per una visita)
Riquadro 7 · le azioni:
  1. vedo le visite in programma
  2. vedo una visita
  3. aggiungo una visita al programma
  4. vedo chi ha prenotato una visita (se la visita non c'è: 404)
  5. prenoto dei posti per una visita (se i posti liberi non bastano: 409, posti esauriti)
  6. disdico una prenotazione

Gli stampi: VisitaNuova e Visita, PrenotazioneNuova e Prenotazione. Dentro PrenotazioneNuova c'è già visita_id: la visita da prenotare arriva nel corpo.

Questa volta nel file non ci sono i commenti per ogni rotta: le scrivi tutte tu, nell'ordine del canvas.

Come provi: pytest palestra/test_visite.py -v

Aiutino 1
Due cose, due risorse: /visite e /prenotazioni. Per ogni azione chiediti prima di quale delle due parla, poi legge o scrive, poi una o tante.
Aiutino 2
«Vedo chi ha prenotato una visita» parte da una visita che deve esistere: sotto-risorsa, /visite/{visita_id}/prenotazioni. «Prenoto» invece crea una prenotazione, e la visita è già nel corpo: POST /prenotazioni.
Aiutino 3
Il 409 nel contratto: responses={409: {"description": "Posti esauriti"}} nel decoratore, accanto a status_code. Se la riga diventa lunga, vai a capo dopo la parentesi, un pezzo per riga, come la POST /permessi della teoria.

Finito? Accendi ognuno dei tre e apri /docs: è quello che vedrà chi userà le tue API. Poi confronta con le soluzioni, che mostrano anche le tre tabelle delle rotte.

E poi tocca al tuo progetto: prendi il tuo canvas, riquadri 6, 7 e 8, e scrivi la tua tabella delle rotte. Da 5 a 10 righe, in un ROTTE.md nel repository del progetto.