Il contratto, esercizi spiegati
Cinque esempi, dal foglio a /docs
- 25 minuti di lettura
Cinque esempi, dal più semplice. Ognuno ha lo stesso ritmo:
- Prevedi: prima di aprire la risposta, scrivi su un foglio la tua. Qui spesso non è un output: è una riga della tabella, o un percorso.
- In italiano: il ragionamento, a parole.
- Passo per passo: una riga alla volta.
- Cosa portiamo a casa: la cosa da ricordare.
Gli esempi con FastAPI si provano così: copia il codice in un file nella cartella dello zip (per esempio accompagnamenti.py), accendilo con fastapi dev accompagnamenti.py e fai le richieste da un secondo terminale.
A · La bozza di Tommaso
Tommaso Greco, macchinista, vuole un registro dei ritardi: per ogni ritardo, il treno, la stazione e i minuti. Nel suo riquadro 6 c'è una cosa sola: i ritardi. Ha scritto di getto sei richieste:
1. GET /getRitardi
2. POST /ritardo
3. GET /ritardi?id=12
4. POST /ritardi/12/cancella
5. GET /ritardi/treno/M12
6. PUT /Ritardi/12Ognuna infrange una delle cinque regole. Quale? E come la riscrivi?
Prevedi Scrivi su un foglio cosa ti aspetti, poi apri.
| # | La regola infranta | Riscritta |
|---|---|---|
| 1 | 1 · Nomi: get è un verbo | GET /ritardi |
| 2 | 1 · Al plurale | POST /ritardi |
| 3 | 3 · L'id nel percorso | GET /ritardi/12 |
| 4 | 2 · Il verbo HTTP dice l'azione | DELETE /ritardi/12 |
| 5 | 4 · I filtri nella query | GET /ritardi?treno=M12 |
| 6 | 5 · Minuscole | PUT /ritardi/12 |
In italiano. Per ogni riga mi faccio cinque domande, sempre nello stesso ordine:
- I pezzi fissi del percorso sono solo nomi del riquadro 6, al plurale?
- C'è un verbo nel percorso? Allora va tolto, e l'azione passa al verbo HTTP.
- Si parla di una cosa sola? Il suo id va nel percorso.
- Si restringe un elenco? Il filtro va dopo il
?. - Tutto minuscolo, e le parole unite dal trattino?
Passo per passo, le due righe più difficili:
| Riga | La domanda che la ferma | Il ragionamento |
|---|---|---|
4 · POST /ritardi/12/cancella | 2 · c'è un verbo nel percorso? | «cancella» è un verbo. Cosa succede al ritardo 12? Sparisce: DELETE. Tolto il verbo, resta /ritardi/12, il ritardo 12 |
5 · GET /ritardi/treno/M12 | 1 · solo nomi del riquadro 6? | «treno» non è una cosa del riquadro 6, e M12 non è l'id di un ritardo: è il treno a cui il ritardo è capitato, una sua caratteristica. Restringe l'elenco: è un filtro, ?treno=M12 |
Senza filtro, GET /ritardi dà tutti i ritardi. Con il filtro, solo quelli dell'M12. Un percorso solo, due usi.
Cosa portiamo a casa. Cinque domande, nell'ordine, per ogni riga. Le prime due da sole fermano metà degli errori: nel percorso solo nomi, e il verbo lo fa il verbo.
B · Dal canvas alla tabella: l'accompagnamento
Lucia Ferri, capotreno, coordina l'accompagnamento: chi ha bisogno di aiuto (una sedia a rotelle, un passeggino, la vista che non c'è più) prenota, e un addetto lo aspetta all'ingresso della stazione e lo porta fino al treno. Rosa Bellini lo prenota spesso per i clienti della sua agenzia di viaggi, e vorrebbe farlo direttamente dal programma dell'agenzia. Serve un'API: prima ancora, un contratto. Il canvas di Lucia:
Riquadro 6 · le cose
gli accompagnamenti: a nome di chi, in quale stazione, che giorno, a che ora
Riquadro 7 · le azioni
1. prenoto un accompagnamento
2. vedo gli accompagnamenti, anche solo quelli di una stazione
3. vedo un accompagnamento
4. cambio l'ora di un accompagnamento
5. annullo un accompagnamento
Riquadro 8 · chi può fare cosa
prenotare, vedere, cambiare e annullare: chi ha fatto il login;
vedere tutti gli accompagnamenti: solo gli addettiScrivi la tabella delle rotte: Azione, Richiesta, Mando → Ricevo, Codici, Login.
Prevedi Scrivi su un foglio cosa ti aspetti, poi apri.
| Azione | Richiesta | Mando → Ricevo | Codici | Login |
|---|---|---|---|---|
| 1. Prenoto | POST /accompagnamenti | nome, stazione, giorno, ora → l'accompagnamento con il suo id | 201, 422 | sì |
| 2. Vedo, anche di una stazione | GET /accompagnamenti?stazione_id=3 | niente → la lista degli accompagnamenti | 200 | sì, gli addetti |
| 3. Vedo uno | GET /accompagnamenti/{accompagnamento_id} | niente → l'accompagnamento | 200, 404 | sì |
| 4. Cambio l'ora | PUT /accompagnamenti/{accompagnamento_id} | tutti i campi, con l'ora nuova → l'accompagnamento cambiato | 200, 404, 422 | sì |
| 5. Annullo | DELETE /accompagnamenti/{accompagnamento_id} | niente → niente | 204, 404 | sì |
In italiano. Una cosa sola nel riquadro 6: una risorsa sola, /accompagnamenti. Per ogni azione mi chiedo due cose: legge o scrive? Parla di una cosa o di tante? Da lì vengono il verbo e il percorso.
Passo per passo.
| Azione | Legge o scrive? | Una o tante? | Verbo | Percorso |
|---|---|---|---|---|
| 1. Prenoto | scrive: nasce una cosa | una, nuova: il suo id non c'è ancora | POST | /accompagnamenti |
| 2. Vedo, anche di una stazione | legge | tante, forse ristrette | GET | /accompagnamenti, filtro ?stazione_id= |
| 3. Vedo uno | legge | una | GET | /accompagnamenti/{accompagnamento_id} |
| 4. Cambio l'ora | scrive: cambia | una | PUT | /accompagnamenti/{accompagnamento_id} |
| 5. Annullo | scrive: sparisce | una | DELETE | /accompagnamenti/{accompagnamento_id} |
Due cose da notare:
- La stazione, nell'azione 2, è un filtro: le stazioni non sono una cosa di questo canvas, e «nessun accompagnamento a Ponte Ciclo» è una lista vuota, non un errore.
- «Cambio l'ora» è una
PUT: si manda tutto l'accompagnamento, con l'ora nuova (la PUT sostituisce tutto, da Verbi e codici). Non/accompagnamenti/3/ora.
Cosa portiamo a casa. Tre percorsi su cinque sono uguali: /accompagnamenti/{accompagnamento_id}. Li distingue il verbo. È la regola 2 vista dall'altra parte.
C · Dalla tabella a FastAPI
La tabella di Lucia, scritta in FastAPI. Gli stampi sono due, come nel capitolo 7: quello senza id (lo manda il client) e quello con l'id (lo restituisce il server).
from fastapi import FastAPI, HTTPException, status
from pydantic import BaseModel
app = FastAPI(title="L'accompagnamento della Linea Menta")
class AccompagnamentoNuovo(BaseModel):
nome: str
stazione_id: int
giorno: str
ora: str
class Accompagnamento(AccompagnamentoNuovo):
id: int
# 1. prenoto un accompagnamento · login: sì
@app.post("/accompagnamenti", status_code=status.HTTP_201_CREATED)
def nuovo_accompagnamento(dati: AccompagnamentoNuovo) -> Accompagnamento:
raise HTTPException(status_code=501, detail="Contratto: la rotta c'è, il codice arriva dopo")
# 2. vedo gli accompagnamenti, anche solo quelli di una stazione · login: sì, gli addetti
@app.get("/accompagnamenti")
def lista_accompagnamenti(stazione_id: int | None = None) -> list[Accompagnamento]:
raise HTTPException(status_code=501, detail="Contratto: la rotta c'è, il codice arriva dopo")
# 3. vedo un accompagnamento · login: sì
@app.get("/accompagnamenti/{accompagnamento_id}")
def leggi_accompagnamento(accompagnamento_id: int) -> Accompagnamento:
raise HTTPException(status_code=501, detail="Contratto: la rotta c'è, il codice arriva dopo")
# 4. cambio l'ora di un accompagnamento · login: sì
@app.put("/accompagnamenti/{accompagnamento_id}")
def sostituisci_accompagnamento(accompagnamento_id: int, dati: AccompagnamentoNuovo) -> Accompagnamento:
raise HTTPException(status_code=501, detail="Contratto: la rotta c'è, il codice arriva dopo")
# 5. annullo un accompagnamento · login: sì
@app.delete("/accompagnamenti/{accompagnamento_id}", status_code=status.HTTP_204_NO_CONTENT)
def togli_accompagnamento(accompagnamento_id: int) -> None:
raise HTTPException(status_code=501, detail="Contratto: la rotta c'è, il codice arriva dopo")Salva il codice come accompagnamenti.py. Nel primo terminale (il server): fastapi dev accompagnamenti.py. Nel secondo terminale (venv acceso), quattro richieste. Che codice risponde ognuna? Attento: dentro le rotte non c'è codice.
curl -i -X DELETE http://127.0.0.1:8000/accompagnamenti/3
curl -i http://127.0.0.1:8000/accompagnamenti/tre
curl -i -X POST http://127.0.0.1:8000/accompagnamenti \
-H "Content-Type: application/json" \
-d '{"nome": "Rosa Bellini", "stazione_id": 5, "giorno": "lunedì"}'
curl -i http://127.0.0.1:8000/accompagnamenti/3/annullaPrevedi Scrivi su un foglio cosa ti aspetti, poi apri.
Nel terminale del server compare:
INFO: 127.0.0.1:60528 - "DELETE /accompagnamenti/3 HTTP/1.1" 501 Not Implemented
INFO: 127.0.0.1:60529 - "GET /accompagnamenti/tre HTTP/1.1" 422 Unprocessable Entity
INFO: 127.0.0.1:60530 - "POST /accompagnamenti HTTP/1.1" 422 Unprocessable Entity
INFO: 127.0.0.1:60531 - "GET /accompagnamenti/3/annulla HTTP/1.1" 404 Not FoundE i corpi delle risposte, uno per richiesta:
{"detail":"Contratto: la rotta c'è, il codice arriva dopo"}
{"detail":[{"type":"int_parsing","loc":["path","accompagnamento_id"],"msg":"Input should be a valid integer, unable to parse string as an integer","input":"tre"}]}
{"detail":[{"type":"missing","loc":["body","ora"],"msg":"Field required","input":{"nome":"Rosa Bellini","stazione_id":5,"giorno":"lunedì"}}]}
{"detail":"Not Found"}In italiano.
DELETE /accompagnamenti/3: la rotta c'è, il codice no. Il 501.trenon è un numero, e il contratto diceaccompagnamento_id: int. FastAPI controlla prima di entrare nella funzione, e risponde 422 da solo: il 501 non lo raggiunge nemmeno.- Nel corpo manca l'ora, e lo stampo
AccompagnamentoNuovola vuole. Di nuovo 422, con illocche dice dove:body,ora. /accompagnamenti/3/annullanon è nel contratto: per FastAPI quell'indirizzo non esiste. 404,Not Found.
Il disegno.
Passo per passo, dalla riga della tabella alla riga del def:
| Nella tabella | Nel def |
|---|---|
?stazione_id=3, un filtro che può mancare | stazione_id: int | None = None |
| l'id nel percorso | {accompagnamento_id} nel decoratore e accompagnamento_id: int nel def, uguali lettera per lettera |
| mando nome, stazione, giorno, ora | dati: AccompagnamentoNuovo, nella POST e nella PUT |
| ricevo la lista, o uno solo | -> list[Accompagnamento], -> Accompagnamento |
| 201, 204 | status_code= nel decoratore |
| ricevo niente | -> None, insieme al 204 |
Cosa portiamo a casa. Il contratto in FastAPI è già un server. Dove manca il codice risponde 501, ma il 422 e il 404 li dà già giusti, da solo: tre richieste su quattro hanno già avuto la risposta giusta.
D · Filtro o sotto-risorsa, dal vivo
Torniamo ai musicisti della teoria. Qui le rotte sono due modi di chiedere la stessa cosa, «i permessi di un musicista», e dentro c'è il codice vero, quello del capitolo 7.
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
app = FastAPI(title="I permessi dei musicisti")
class Musicista(BaseModel):
id: int
nome: str
strumento: str
class Permesso(BaseModel):
id: int
musicista_id: int
stazione_id: int
giorno: str
musicisti = {
1: Musicista(id=1, nome="Bruno Testa", strumento="fisarmonica"),
2: Musicista(id=2, nome="Gina Porro", strumento="violino"),
}
permessi = {
1: Permesso(id=1, musicista_id=1, stazione_id=3, giorno="sabato"),
2: Permesso(id=2, musicista_id=2, stazione_id=5, giorno="sabato"),
3: Permesso(id=3, musicista_id=1, stazione_id=5, giorno="domenica"),
}
# Il filtro: la lista dei permessi, ristretta
@app.get("/permessi")
def lista_permessi(musicista_id: int | None = None) -> list[Permesso]:
trovati = []
for permesso in permessi.values():
if musicista_id is None or permesso.musicista_id == musicista_id:
trovati.append(permesso)
return trovati
# La sotto-risorsa: i permessi DI un musicista, che deve esistere
@app.get("/musicisti/{musicista_id}/permessi")
def permessi_del_musicista(musicista_id: int) -> list[Permesso]:
if musicista_id not in musicisti:
raise HTTPException(status_code=404, detail="Musicista non trovato")
trovati = []
for permesso in permessi.values():
if permesso.musicista_id == musicista_id:
trovati.append(permesso)
return trovatiSalva il codice come permessi.py e accendilo: fastapi dev permessi.py. Il musicista 1 c'è, il 9 no. Cosa risponde ognuna di queste quattro?
curl -i "http://127.0.0.1:8000/permessi?musicista_id=1"
curl -i http://127.0.0.1:8000/musicisti/1/permessi
curl -i "http://127.0.0.1:8000/permessi?musicista_id=9"
curl -i http://127.0.0.1:8000/musicisti/9/permessiPrevedi Scrivi su un foglio cosa ti aspetti, poi apri.
Le prime due rispondono uguale, 200 e gli stessi due permessi:
HTTP/1.1 200 OK
date: Thu, 19 Nov 2026 16:10:14 GMT
server: uvicorn
content-length: 123
content-type: application/json
[{"id":1,"musicista_id":1,"stazione_id":3,"giorno":"sabato"},{"id":3,"musicista_id":1,"stazione_id":5,"giorno":"domenica"}]Le ultime due no. Il filtro, con il musicista 9:
HTTP/1.1 200 OK
date: Thu, 19 Nov 2026 16:10:14 GMT
server: uvicorn
content-length: 2
content-type: application/json
[]La sotto-risorsa, con il musicista 9:
HTTP/1.1 404 Not Found
date: Thu, 19 Nov 2026 16:10:14 GMT
server: uvicorn
content-length: 34
content-type: application/json
{"detail":"Musicista non trovato"}In italiano. Tutte e due le rotte scorrono i permessi con il setaccio: lista vuota, for, if, append. La sotto-risorsa, prima, controlla che il musicista esista: prima il 404, poi il lavoro. Il filtro non lo chiede a nessuno: se nessun permesso ha musicista_id uguale a 9, la lista resta vuota.
Il disegno.
Passo per passo.
| Richiesta | Controlla il musicista? | Il musicista c'è? | Risposta |
|---|---|---|---|
GET /permessi?musicista_id=1 | no | non lo chiede | 200, due permessi |
GET /musicisti/1/permessi | sì | sì | 200, gli stessi due |
GET /permessi?musicista_id=9 | no | non lo chiede | 200, [] |
GET /musicisti/9/permessi | sì | no | 404, Musicista non trovato |
Cosa portiamo a casa. Per chi usa l'API, [] e 404 sono due messaggi diversi: «non ha permessi» e «non esiste». Il contratto sceglie quale dei due dare, e la scelta si vede già nel percorso.
E · Il contratto con gli occhi dei test
Il contratto di musicisti.py, quello della teoria, si può leggere anche da Python: app.openapi() restituisce lo stesso dizionario che /openapi.json manda al browser. Salva questo file come leggi_contratto.py, accanto a musicisti.py:
import json
from musicisti import app
contratto = app.openapi()
for percorso, verbi in contratto["paths"].items():
for verbo in verbi:
print(verbo.upper(), percorso)
scheda = contratto["paths"]["/permessi"]["post"]
print(json.dumps(scheda, indent=2, ensure_ascii=False))python3 leggi_contratto.pyLe rotte in musicisti.py sono quattro. Quante righe stampa il primo for, e in che ordine? E nella scheda di POST /permessi, dove trovi lo stampo del corpo, il 201 e il 409?
Prevedi Scrivi su un foglio cosa ti aspetti, poi apri.
GET /permessi
POST /permessi
GET /musicisti/{musicista_id}/permessi
DELETE /permessi/{permesso_id}
{
"summary": "Nuovo Permesso",
"operationId": "nuovo_permesso_permessi_post",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PermessoNuovo"
}
}
}
},
"responses": {
"201": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Permesso"
}
}
}
},
"409": {
"description": "Stazione già presa quel giorno"
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}Quattro righe, una per rotta. Ma i percorsi sono tre: GET e POST /permessi stanno sotto lo stesso percorso, uno accanto all'altro.
In italiano. Il contratto è un dizionario di dizionari: percorso → verbo → la scheda della rotta. Nella scheda:
requestBodyè cosa mando: lo stampoPermessoNuovo. UnaGETo unaDELETEnon ce l'hanno;responsessono i codici, e dentro ognuno cosa ricevo: con il 201 torna unPermesso; il 409 ha solo la sua frase; il 422 l'ha messo FastAPI;parameters, quando c'è, elenca i dati del percorso e della query, ognuno con il suo"in":"path"o"query". Qui manca, perché laPOST /permessinon ne ha.
Passo per passo, da dove viene ogni pezzo della scheda:
| Nella scheda | Dal codice |
|---|---|
"summary": "Nuovo Permesso" | il nome della funzione, nuovo_permesso, con le maiuscole e gli spazi |
"requestBody" con PermessoNuovo | dati: PermessoNuovo nel def |
"201" con Permesso | status_code=status.HTTP_201_CREATED e -> Permesso |
"409" | responses= nel decoratore |
"422" | FastAPI, da solo: c'è un corpo da controllare |
Cosa portiamo a casa. I test della palestra fanno proprio questo: cercano ("POST", "/permessi") nel contratto, poi guardano requestBody e responses. Per questo non chiamano le rotte, e non hanno bisogno del server acceso: leggono il contratto.
Pronto? Nella palestra ti aspettano tre servizi della Linea Menta, dal ★ al ★★★: il canvas c'è già, il contratto lo scrivi tu.