Vai al contenuto
code-to-code

Apro l'indice…

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

HTTP e API8. Il contrattop. 224

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 login

Nel 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 commissario

Dal canvas alle rotte, in cinque passi

  1. 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.
  2. Le azioni. Ogni azione del riquadro 7 diventa una richiesta.
  3. Il verbo. Legge: GET. Crea: POST. Cambia: PUT. Cancella: DELETE.
  4. La riga. Per ogni richiesta: il percorso, cosa mando, cosa ricevo, i codici.
  5. 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:

AzioneRichiestaMando → RicevoCodiciLogin
1. Vedo i permessi, anche di un giornoGET /permessi?giorno=sabatoniente → la lista dei permessi200no
2. I permessi di un musicistaGET /musicisti/{musicista_id}/permessiniente → la lista dei suoi permessi200, 404no
3. Iscrivo un musicistaPOST /musicistinome, strumento → il musicista con il suo id201, 422sì
4. Do un permessoPOST /permessimusicista, stazione, giorno → il permesso con il suo id201, 409, 422sì
5. Sposto un permessoPUT /permessi/{permesso_id}tutti i campi → il permesso cambiato200, 404, 409, 422sì
6. Revoco un permessoDELETE /permessi/{permesso_id}niente → niente204, 404sì

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

RegolaSìNo
1. Nomi, al pluraleGET /permessiGET /getPermessi, GET /permesso
2. Il verbo HTTP dice l'azioneDELETE /permessi/7POST /permessi/7/revoca
3. L'id nel percorsoGET /permessi/7GET /permessi?id=7
4. I filtri nella queryGET /permessi?giorno=sabatoGET /permessi/giorno/sabato
5. Minuscole e trattini/musicisti-di-strada/MusicistiDiStrada, /musicisti_di_strada

Il perché, in una riga per regola:

  1. Un percorso è un nome: /permessi è il quaderno dei permessi, /permessi/7 la pagina 7. Al plurale anche quando ne chiedi uno: è il 7 dei permessi.
  2. 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.
  3. 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).
  4. 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.
  5. 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 del def.

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 4

Quando 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:

Python
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 tabellaNel contratto in FastAPI
il verbo e il percorsoil decoratore: @app.post("/permessi")
l'id nel percorsoil nome tra graffe, e lo stesso nome nel def, con int: permesso_id: int
un filtroun argomento con = None: giorno: str | None = None
cosa mando nel corpouno stampo nel def: dati: PermessoNuovo, senza id (l'id lo sceglie il server)
cosa ricevola freccia: -> Permesso, -> list[Permesso], oppure -> None
il codice di quando va benestatus_code= nel decoratore, se non è 200: status.HTTP_201_CREATED, status.HTTP_204_NO_CONTENT
un errore che il client deve conoscereresponses= nel decoratore: un dizionario codice → descrizione
il loginper 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):

Terminale
fastapi dev musicisti.py

Nel secondo terminale (venv acceso), chiedi un permesso nuovo:

Terminale
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, crea POST (201), cambia PUT, cancella DELETE (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, def e freccia, e dentro il 501. /docs lo fa leggere a tutti.