Vai al contenuto
code-to-code

Apro l'indice…

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

HTTP e API8. Il contrattop. 231

Il contratto, esercizi spiegati

Cinque esempi, dal foglio a /docs

  • 25 minuti di lettura

Cinque esempi, dal più semplice. Ognuno ha lo stesso ritmo:

  1. Prevedi: prima di aprire la risposta, scrivi su un foglio la tua. Qui spesso non è un output: è una riga della tabella, o un percorso.
  2. In italiano: il ragionamento, a parole.
  3. Passo per passo: una riga alla volta.
  4. 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/12

Ognuna infrange una delle cinque regole. Quale? E come la riscrivi?

Prevedi Scrivi su un foglio cosa ti aspetti, poi apri.
#La regola infrantaRiscritta
11 · Nomi: get è un verboGET /ritardi
21 · Al pluralePOST /ritardi
33 · L'id nel percorsoGET /ritardi/12
42 · Il verbo HTTP dice l'azioneDELETE /ritardi/12
54 · I filtri nella queryGET /ritardi?treno=M12
65 · MinuscolePUT /ritardi/12

In italiano. Per ogni riga mi faccio cinque domande, sempre nello stesso ordine:

  1. I pezzi fissi del percorso sono solo nomi del riquadro 6, al plurale?
  2. C'è un verbo nel percorso? Allora va tolto, e l'azione passa al verbo HTTP.
  3. Si parla di una cosa sola? Il suo id va nel percorso.
  4. Si restringe un elenco? Il filtro va dopo il ?.
  5. Tutto minuscolo, e le parole unite dal trattino?

Passo per passo, le due righe più difficili:

RigaLa domanda che la fermaIl ragionamento
4 · POST /ritardi/12/cancella2 · 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/M121 · 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 addetti

Scrivi la tabella delle rotte: Azione, Richiesta, Mando → Ricevo, Codici, Login.

Prevedi Scrivi su un foglio cosa ti aspetti, poi apri.
AzioneRichiestaMando → RicevoCodiciLogin
1. PrenotoPOST /accompagnamentinome, stazione, giorno, ora → l'accompagnamento con il suo id201, 422sì
2. Vedo, anche di una stazioneGET /accompagnamenti?stazione_id=3niente → la lista degli accompagnamenti200sì, gli addetti
3. Vedo unoGET /accompagnamenti/{accompagnamento_id}niente → l'accompagnamento200, 404sì
4. Cambio l'oraPUT /accompagnamenti/{accompagnamento_id}tutti i campi, con l'ora nuova → l'accompagnamento cambiato200, 404, 422sì
5. AnnulloDELETE /accompagnamenti/{accompagnamento_id}niente → niente204, 404sì

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.

AzioneLegge o scrive?Una o tante?VerboPercorso
1. Prenotoscrive: nasce una cosauna, nuova: il suo id non c'è ancoraPOST/accompagnamenti
2. Vedo, anche di una stazioneleggetante, forse ristretteGET/accompagnamenti, filtro ?stazione_id=
3. Vedo unoleggeunaGET/accompagnamenti/{accompagnamento_id}
4. Cambio l'orascrive: cambiaunaPUT/accompagnamenti/{accompagnamento_id}
5. Annulloscrive: sparisceunaDELETE/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).

Python
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.

Terminale
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/annulla
Prevedi 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 Found

E 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.

  1. DELETE /accompagnamenti/3: la rotta c'è, il codice no. Il 501.
  2. tre non è un numero, e il contratto dice accompagnamento_id: int. FastAPI controlla prima di entrare nella funzione, e risponde 422 da solo: il 501 non lo raggiunge nemmeno.
  3. Nel corpo manca l'ora, e lo stampo AccompagnamentoNuovo la vuole. Di nuovo 422, con il loc che dice dove: body, ora.
  4. /accompagnamenti/3/annulla non è nel contratto: per FastAPI quell'indirizzo non esiste. 404, Not Found.

Il disegno.

inizio arriva una richiesta se il percorso non è nel contratto sì: errore 404 Not Found se il percorso c'è, con un altro verbo sì: errore 405 Method Not Allowed se id o corpo non passano i tipi sì: errore 422 Lo dice FastAPI errore 501 Il codice arriva dopoarriva una richiestail percorso non ènel contratto404 Not Foundil percorso c'è, conun altro verbo405 Method Not Allowedid o corpo nonpassano i tipi422 Lo dice FastAPI501 Il codice arriva doponosìnosìnosì
Cosa risponde il contratto

Passo per passo, dalla riga della tabella alla riga del def:

Nella tabellaNel def
?stazione_id=3, un filtro che può mancarestazione_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, oradati: AccompagnamentoNuovo, nella POST e nella PUT
ricevo la lista, o uno solo-> list[Accompagnamento], -> Accompagnamento
201, 204status_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.

Python
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 trovati

Salva il codice come permessi.py e accendilo: fastapi dev permessi.py. Il musicista 1 c'è, il 9 no. Cosa risponde ognuna di queste quattro?

Terminale
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/permessi
Prevedi 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.

inizio GET /musicisti/{musicista_id}/permessi se musicista_id not in musicisti sì: errore 404 Musicista non trovato trovati = [] per ogni permesso in permessi.values() se permesso.musicista_id == musicista_id sì: trovati.append(permesso) restituisci trovatiGET/musicisti/{musicista_id}/permessimusicista_id not inmusicisti404 Musicista non trovatotrovati = []per ogni permesso inpermessi.values()permesso.musicista_id== musicista_idtrovati.append(permesso)restituisci trovatinosìnosìfiniti
La sotto-risorsa dei permessi

Passo per passo.

RichiestaControlla il musicista?Il musicista c'è?Risposta
GET /permessi?musicista_id=1nonon lo chiede200, due permessi
GET /musicisti/1/permessisìsì200, gli stessi due
GET /permessi?musicista_id=9nonon lo chiede200, []
GET /musicisti/9/permessisìno404, 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:

Python
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))
Terminale
python3 leggi_contratto.py

Le 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 stampo PermessoNuovo. Una GET o una DELETE non ce l'hanno;
  • responses sono i codici, e dentro ognuno cosa ricevo: con il 201 torna un Permesso; 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é la POST /permessi non ne ha.

Passo per passo, da dove viene ogni pezzo della scheda:

Nella schedaDal codice
"summary": "Nuovo Permesso"il nome della funzione, nuovo_permesso, con le maiuscole e gli spazi
"requestBody" con PermessoNuovodati: PermessoNuovo nel def
"201" con Permessostatus_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.