Il contratto
Progettare le rotte prima di scriverle
- 12 minuti di lettura
Nei capitoli 4–7 le rotte te le dava già qualcuno: «scrivi GET /treni/{treno_id}, e se il treno non c'è rispondi 404». Per la tua API, quella del progetto, chi lo decide? Tu. E lo decidi prima di scrivere il codice.
L'elenco delle richieste che la tua API accetta si chiama contratto. È un patto tra chi scrive l'API e chi la usa: l'app dei passeggeri, un frontend scritto da un'altra persona, il programma di un collega. Per ogni richiesta dice: «se mi mandi questo, ti rispondo così».
Perché prima? Perché chi usa l'API ci costruisce sopra. Se cambi /permessi in /permesso, il suo programma chiede un indirizzo che non c'è più e riceve un 404. Cambiare il codice dentro una rotta non rompe niente a nessuno; cambiare il contratto rompe il lavoro degli altri.
Il disegno
Il contratto sta in mezzo, tra il canvas del progetto (lo stesso di Disegnare un database) e il codice dei capitoli 4–7.
IL CANVAS (progetto) IL CONTRATTO IL CODICE (capitoli 4–7)
Riquadro 6 · le cose ───▶ le risorse
/musicisti /permessi
Riquadro 7 · le azioni ───▶ una richiesta per azione: ───▶ una rotta per richiesta:
verbo e percorso @app.get(…)
mando → ricevo def …(…) -> …:
i codici il codice dentro
Riquadro 8 · chi può ───▶ le richieste con il login ───▶ il libro del loginNel mezzo c'è una tabella. Si scrive su un foglio, o in un file ROTTE.md, e solo dopo diventa Python.
L'esempio: i musicisti di strada
Nei corridoi di Largo Lista e di Piazza Query suonano i musicisti di strada. Per suonare serve un permesso: una stazione, un giorno. Adesso i permessi stanno su un quaderno nell'ufficio del commissario Mapelli, e il sabato due fisarmoniche si ritrovano nello stesso corridoio. Il commissario ha riempito il canvas. Ecco i riquadri che servono per le rotte:
Riquadro 6 · le cose
i musicisti: il nome, lo strumento
i permessi: chi suona, in quale stazione, in quale giorno
Riquadro 7 · le azioni
1. vedo i permessi, anche solo quelli di un giorno
2. apro la scheda di un musicista e vedo i suoi permessi
3. iscrivo un musicista
4. do un permesso (se quel giorno la stazione è già presa: no)
5. sposto un permesso in un altro giorno
6. revoco un permesso
Riquadro 8 · chi può fare cosa
tutti vedono i permessi; iscrivere, dare, spostare e revocare: solo il commissarioDal canvas alle rotte, in cinque passi
- Le cose. Ogni cosa del riquadro 6 diventa una risorsa, con un nome al plurale:
/musicisti,/permessi. Saranno anche le tue tabelle: Disegnare un database parte dallo stesso riquadro. - Le azioni. Ogni azione del riquadro 7 diventa una richiesta.
- Il verbo. Legge:
GET. Crea:POST. Cambia:PUT. Cancella:DELETE. - La riga. Per ogni richiesta: il percorso, cosa mando, cosa ricevo, i codici.
- Il login. Dal riquadro 8: quali richieste servono solo a chi ha fatto il login? Per ora basta un sì o un no. Il login vero arriva in Login e rotte protette.
Il risultato è la tabella delle rotte:
| Azione | Richiesta | Mando → Ricevo | Codici | Login |
|---|---|---|---|---|
| 1. Vedo i permessi, anche di un giorno | GET /permessi?giorno=sabato | niente → la lista dei permessi | 200 | no |
| 2. I permessi di un musicista | GET /musicisti/{musicista_id}/permessi | niente → la lista dei suoi permessi | 200, 404 | no |
| 3. Iscrivo un musicista | POST /musicisti | nome, strumento → il musicista con il suo id | 201, 422 | sì |
| 4. Do un permesso | POST /permessi | musicista, stazione, giorno → il permesso con il suo id | 201, 409, 422 | sì |
| 5. Sposto un permesso | PUT /permessi/{permesso_id} | tutti i campi → il permesso cambiato | 200, 404, 409, 422 | sì |
| 6. Revoco un permesso | DELETE /permessi/{permesso_id} | niente → niente | 204, 404 | sì |
Quante righe? Da 5 a 10. Meno di 5: l'app fa troppo poco, o mancano delle azioni. Più di 10: stai facendo troppo, torna al riquadro 4 e taglia i «se avanza tempo».
Le cinque regole dei percorsi
| Regola | Sì | No |
|---|---|---|
| 1. Nomi, al plurale | GET /permessi | GET /getPermessi, GET /permesso |
| 2. Il verbo HTTP dice l'azione | DELETE /permessi/7 | POST /permessi/7/revoca |
| 3. L'id nel percorso | GET /permessi/7 | GET /permessi?id=7 |
| 4. I filtri nella query | GET /permessi?giorno=sabato | GET /permessi/giorno/sabato |
| 5. Minuscole e trattini | /musicisti-di-strada | /MusicistiDiStrada, /musicisti_di_strada |
Il perché, in una riga per regola:
- Un percorso è un nome:
/permessiè il quaderno dei permessi,/permessi/7la pagina 7. Al plurale anche quando ne chiedi uno: è il 7 dei permessi. - Le azioni hanno già un nome: GET, POST, PUT, DELETE. Se nel percorso c'è un verbo (
revoca,crea,get), sta facendo il lavoro che spetta al verbo HTTP. - L'id dice quale cosa: è un pezzo dell'indirizzo, come il numero civico. Nel percorso indica una cosa sola, che c'è (200) o non c'è (404).
- Un filtro restringe una lista, e può mancare: senza filtro, la lista intera. Per questo sta nella query, che è facoltativa: in FastAPI,
giorno: str | None = None, come in La forma della chiamata. - Gli indirizzi si scrivono in minuscolo, e le parole si separano con il trattino. Il trattino basso resta ai nomi Python: nella query si scrive
?musicista_id=1, perché lì il nome è quello di un argomento deldef.
Filtro o sotto-risorsa?
«I permessi di un musicista» si può scrivere in due modi, e in giro li vedrai tutti e due: InfoMenta ha /treni?stazione_id=4, la centrale del capitolo 7 ha /stazioni/4/treni.
GET /permessi?musicista_id=4 un filtro: la lista dei permessi, ristretta
GET /musicisti/4/permessi una sotto-risorsa: i permessi DEL musicista 4Quando il musicista 4 c'è, rispondono la stessa lista. La differenza si vede quando non c'è:
- il filtro risponde 200 e una lista vuota: «nessun permesso con questo filtro»;
- la sotto-risorsa risponde 404: «questo musicista non esiste».
La regola che usiamo nel libro: se la cosa di partenza deve esistere (e se non c'è vuoi un 404), sotto-risorsa. Se è solo un modo di restringere l'elenco, e una lista vuota va bene, filtro. Nel canvas si sente dalla frase: «apro la scheda di un musicista e vedo i suoi permessi» è una sotto-risorsa; «i permessi di sabato» è un filtro, perché sabato non è una cosa del riquadro 6: è una caratteristica del permesso.
Un livello solo: /musicisti/4/permessi sì, /musicisti/4/permessi/7 no. Il permesso 7 ha già il suo id, e l'id basta a trovarlo: /permessi/7.
Il contratto in FastAPI
La tabella è per le persone. Lo stesso contratto si scrive anche in FastAPI, ancora prima del codice: solo i decoratori e le righe del def, e dentro ogni rotta una riga sola, il 501 («non ancora fatto», da Verbi e codici). Ecco quattro righe su sei della tabella:
from fastapi import FastAPI, HTTPException, status
from pydantic import BaseModel
app = FastAPI(title="I musicisti della Linea Menta")
class PermessoNuovo(BaseModel):
musicista_id: int
stazione_id: int
giorno: str
class Permesso(PermessoNuovo):
id: int
# 1. vedo i permessi, anche solo quelli di un giorno · login: no
@app.get("/permessi")
def lista_permessi(giorno: str | None = None) -> list[Permesso]:
raise HTTPException(status_code=501, detail="Contratto: la rotta c'è, il codice arriva dopo")
# 2. vedo i permessi di un musicista · login: no
@app.get("/musicisti/{musicista_id}/permessi")
def permessi_del_musicista(musicista_id: int) -> list[Permesso]:
raise HTTPException(status_code=501, detail="Contratto: la rotta c'è, il codice arriva dopo")
# 4. do un permesso · login: sì
@app.post(
"/permessi",
status_code=status.HTTP_201_CREATED,
responses={409: {"description": "Stazione già presa quel giorno"}},
)
def nuovo_permesso(dati: PermessoNuovo) -> Permesso:
raise HTTPException(status_code=501, detail="Contratto: la rotta c'è, il codice arriva dopo")
# 6. revoco un permesso · login: sì
@app.delete("/permessi/{permesso_id}", status_code=status.HTTP_204_NO_CONTENT)
def togli_permesso(permesso_id: int) -> None:
raise HTTPException(status_code=501, detail="Contratto: la rotta c'è, il codice arriva dopo")Ogni colonna della tabella ha il suo posto:
| Nella tabella | Nel contratto in FastAPI |
|---|---|
| il verbo e il percorso | il decoratore: @app.post("/permessi") |
| l'id nel percorso | il nome tra graffe, e lo stesso nome nel def, con int: permesso_id: int |
| un filtro | un argomento con = None: giorno: str | None = None |
| cosa mando nel corpo | uno stampo nel def: dati: PermessoNuovo, senza id (l'id lo sceglie il server) |
| cosa ricevo | la freccia: -> Permesso, -> list[Permesso], oppure -> None |
| il codice di quando va bene | status_code= nel decoratore, se non è 200: status.HTTP_201_CREATED, status.HTTP_204_NO_CONTENT |
| un errore che il client deve conoscere | responses= nel decoratore: un dizionario codice → descrizione |
| il login | per ora un commento sopra la rotta: # login: sì |
Quando il decoratore diventa lungo, vai a capo dopo la parentesi e metti un pezzo per riga, come in una lista lunga: è la POST qui sopra.
Il contratto, acceso
Il contratto in FastAPI non è un disegno: è già un server. Copia il codice in un file musicisti.py, nella cartella dello zip del capitolo (~/corso/http-contratto, con il venv acceso), e accendilo.
Nel primo terminale (il server):
fastapi dev musicisti.pyNel secondo terminale (venv acceso), chiedi un permesso nuovo:
curl -i -X POST http://127.0.0.1:8000/permessi \
-H "Content-Type: application/json" \
-d '{"musicista_id": 1, "stazione_id": 3, "giorno": "sabato"}'HTTP/1.1 501 Not Implemented
date: Thu, 19 Nov 2026 16:09:47 GMT
server: uvicorn
content-length: 60
content-type: application/json
{"detail":"Contratto: la rotta c'è, il codice arriva dopo"}Una risposta onesta: la rotta c'è, il codice no. Chi scrive l'app dei passeggeri può già cominciare: sa quale indirizzo chiamare, cosa mandare e cosa gli tornerà indietro.
Adesso apri http://127.0.0.1:8000/docs. Ogni rotta è una riga colorata, con il verbo e il percorso. Clicca su POST /permessi: sotto Parameters non c'è niente, sotto Request body c'è lo stampo PermessoNuovo con i suoi tre campi, sotto Responses il 201 con un Permesso, il 409 con la sua frase, e il 422 che FastAPI aggiunge da solo. Chiunque lo legge, senza leggere il Python. E /openapi.json è lo stesso contratto in JSON: è da lì che nasce /docs, ed è proprio quello che leggono i test di questo capitolo.
E dopo
Il contratto è scritto, le rotte rispondono 501. Il codice dentro lo sai già scrivere: è CRUD su un dizionario. Poi i dati passeranno nel database (Perché un database) e le rotte con «login: sì» diventeranno protette. Il contratto, intanto, non cambia: cambia solo quello che c'è dentro le rotte. È il motivo per cui si scrive prima.
Ricorda
- Prima il contratto, poi il codice: chi usa l'API ci costruisce sopra.
- Riquadro 6 → le risorse; riquadro 7 → una richiesta per azione; riquadro 8 → le richieste con il login.
- Legge
GET, creaPOST(201), cambiaPUT, cancellaDELETE(204). - Nomi al plurale, il verbo dice l'azione, l'id nel percorso, i filtri nella query, minuscole e trattini.
- La cosa di partenza deve esistere? Sotto-risorsa, e 404. Restringi un elenco? Filtro, e lista vuota.
- In FastAPI: decoratore,
defe freccia, e dentro il 501./docslo fa leggere a tutti.