Il primo server, esercizi spiegati
Cinque esempi, una richiesta alla volta
- 20 minuti di lettura
Marta Villa, la capostazione di Piazza Query, vuole una bacheca per la sua stazione: un server con il saluto, lo stato della stazione e gli annunci. Cinque esempi, dal più semplice. Ognuno ha lo stesso ritmo:
- Prevedi: leggi il codice e la richiesta, e scrivi su un foglio cosa risponde il server. Prima di aprire la risposta.
- In italiano: cosa fa il codice, a parole.
- Passo per passo: cosa succede alla richiesta, un pezzo alla volta.
- Cosa portiamo a casa: la cosa da ricordare.
Ogni esempio si può provare: crea bacheca.py nella cartella dello zip della palestra, accanto a palestra/. Nel primo terminale accendi il server con fastapi dev bacheca.py e lascialo acceso: a ogni salvataggio si riavvia da solo. Nel secondo terminale (venv acceso) fai le richieste.
A · Il saluto della bacheca
Il primo pezzo della bacheca:
# bacheca.py
from fastapi import FastAPI
app = FastAPI(title="La bacheca di Piazza Query")
@app.get("/")
def saluto():
return {"stazione": "Piazza Query", "capostazione": "Marta Villa"}Con il server acceso, nel secondo terminale:
curl -i http://127.0.0.1:8000/Prevedi: il codice della risposta, il content-type, il corpo.
Prevedi Scrivi su un foglio cosa ti aspetti, poi apri.
HTTP/1.1 200 OK
date: Thu, 19 Nov 2026 16:07:57 GMT
server: uvicorn
content-length: 56
content-type: application/json
{"stazione":"Piazza Query","capostazione":"Marta Villa"}200 OK: la rotta c'è, e la funzione è arrivata alreturnsenza errori.content-type: application/json: lo mette FastAPI, perché il corpo è JSON. Tu non l'hai scritto da nessuna parte.- Il corpo è il dizionario scritto come JSON: virgolette doppie, niente spazi.
- La data è quella del momento: la tua sarà diversa.
In italiano.
- Creo l'applicazione, con il suo nome.
- Collego la funzione
salutoalle richieste GET sul percorso/. - La funzione restituisce un dizionario con due chiavi.
Il disegno.
Passo per passo.
| Passo | Dove | Cosa succede |
|---|---|---|
| 1 | secondo terminale | curl manda GET / HTTP/1.1 al tuo computer, porta 8000 |
| 2 | primo terminale | uvicorn riceve la richiesta e la passa a FastAPI |
| 3 | FastAPI | cerca una rotta con il verbo GET e il percorso /: è saluto |
| 4 | bacheca.py | saluto() restituisce il dizionario |
| 5 | FastAPI | trasforma il dizionario in testo JSON e aggiunge content-type: application/json |
| 6 | secondo terminale | curl stampa la risposta: 200 e il JSON |
| 7 | primo terminale | il registro scrive "GET / HTTP/1.1" 200 OK |
Cosa portiamo a casa. Tu scrivi la funzione e il suo return. Ricevere la richiesta, trovare la rotta, fare il JSON e mandare la risposta: lo fa FastAPI.
B · Dal dizionario al JSON
Marta aggiunge a bacheca.py lo stato della stazione, e salva:
@app.get("/stazione")
def stazione():
return {
"nome": "Piazza Query",
"aperta": True,
"ascensore_funziona": False,
"binari": (1, 2),
"gradi": 21.5,
"annuncio_urgente": None,
"nota": "Uscita più comoda: lato Largo Lista",
}curl -s http://127.0.0.1:8000/stazionePrevedi: il testo esatto che stampa curl. Con -s stampa solo il corpo.
Prevedi Scrivi su un foglio cosa ti aspetti, poi apri.
{"nome":"Piazza Query","aperta":true,"ascensore_funziona":false,"binari":[1,2],"gradi":21.5,"annuncio_urgente":null,"nota":"Uscita più comoda: lato Largo Lista"}Le chiavi restano nello stesso ordine. Cambiano i valori che in JSON si scrivono in un altro modo.
In italiano. La rotta restituisce un dizionario con sette chiavi, e ogni valore è di un tipo diverso: un testo, un vero, un falso, una tupla, un numero con la virgola, un None, un testo con l'accento. FastAPI traduce ognuno nel suo modo JSON.
Passo per passo, chiave per chiave:
| Chiave | In Python | Nel JSON |
|---|---|---|
"nome" | "Piazza Query" | "Piazza Query" |
"aperta" | True | true |
"ascensore_funziona" | False | false |
"binari" | (1, 2), una tupla | [1,2]: il JSON non ha tuple, solo liste |
"gradi" | 21.5 | 21.5 |
"annuncio_urgente" | None | null |
"nota" | "Uscita più comoda…" | uguale, con la ù così com'è |
Cosa portiamo a casa. Nel file scrivi Python: True, None, le tuple. Il JSON lo scrive FastAPI, e ogni valore Python ha il suo modo di arrivare dall'altra parte.
C · Il return dimenticato
Adesso gli annunci. Marta li tiene in una lista, nel file, e sotto scrive la rotta così:
annunci = ["Ascensore fermo fino alle 12", "Binario 2: un treno ogni 5 minuti"]
@app.get("/annunci")
def lista_annunci():
print(annunci)curl -i http://127.0.0.1:8000/annunciPrevedi: cosa stampa curl? E cosa compare nel terminale del server?
Prevedi Scrivi su un foglio cosa ti aspetti, poi apri.
Nel secondo terminale, curl:
HTTP/1.1 200 OK
date: Thu, 19 Nov 2026 16:08:05 GMT
server: uvicorn
content-length: 4
content-type: application/json
nullNel terminale del server:
['Ascensore fermo fino alle 12', 'Binario 2: un treno ogni 5 minuti']
INFO: 127.0.0.1:60341 - "GET /annunci HTTP/1.1" 200 OKLa lista c'è, ma nel posto sbagliato: print scrive nel terminale dove gira il programma, cioè quello del server. La funzione finisce senza return, quindi restituisce None, e None in JSON è null.
In italiano. La funzione stampa la lista, poi finisce. Senza return, restituisce None.
Passo per passo, le due versioni a confronto:
Con print(annunci) | Con return annunci | |
|---|---|---|
| Dove va la lista | nel terminale del server, a te | nella risposta, al client |
| Cosa restituisce la funzione | None | la lista |
| Il corpo della risposta | null | ["Ascensore fermo fino alle 12","Binario 2: un treno ogni 5 minuti"] |
| Il codice | 200 | 200 |
La correzione sta in una riga: return annunci al posto di print(annunci). Salvi, e curl risponde:
HTTP/1.1 200 OK
date: Thu, 19 Nov 2026 16:08:09 GMT
server: uvicorn
content-length: 68
content-type: application/json
["Ascensore fermo fino alle 12","Binario 2: un treno ogni 5 minuti"]Cosa portiamo a casa. Il client vede solo il return. Il print è un messaggio per te, nel terminale del server: utile per capire cosa succede, invisibile per chi fa la richiesta. È la regola di Le funzioni: print mostra, return consegna.
D · Le strade che non ci sono
La bacheca ha tre rotte, tutte GET: /, /stazione, /annunci. Cinque richieste:
curl -i http://127.0.0.1:8000/annunci
curl -i http://127.0.0.1:8000/annuncio
curl -i http://127.0.0.1:8000/Annunci
curl -i -X POST http://127.0.0.1:8000/annunci
curl -i http://127.0.0.1:8000/annunci/Prevedi: che codice risponde ognuna?
Prevedi Scrivi su un foglio cosa ti aspetti, poi apri.
Nel terminale del server, una riga per richiesta:
INFO: 127.0.0.1:60343 - "GET /annunci HTTP/1.1" 200 OK
INFO: 127.0.0.1:60344 - "GET /annuncio HTTP/1.1" 404 Not Found
INFO: 127.0.0.1:60345 - "GET /Annunci HTTP/1.1" 404 Not Found
INFO: 127.0.0.1:60346 - "POST /annunci HTTP/1.1" 405 Method Not Allowed
INFO: 127.0.0.1:60347 - "GET /annunci/ HTTP/1.1" 307 Temporary RedirectLa quinta è quella che non ti aspetti. Ecco cosa stampa curl:
HTTP/1.1 307 Temporary Redirect
date: Thu, 19 Nov 2026 16:08:09 GMT
server: uvicorn
content-length: 0
location: http://127.0.0.1:8000/annunciIn italiano. Per ogni richiesta FastAPI cerca una rotta con lo stesso verbo e lo stesso percorso, lettera per lettera. Se non la trova, la risposta dice perché: il percorso non c'è (404), c'è ma con un altro verbo (405), c'è senza la barra in fondo (307).
Il disegno.
Passo per passo, richiesta per richiesta:
| Richiesta | FastAPI cerca | Trova | Risponde |
|---|---|---|---|
GET /annunci | una rotta GET su /annunci | lista_annunci | 200 e la lista |
GET /annuncio | una rotta GET su /annuncio | niente: manca una lettera | 404 {"detail":"Not Found"} |
GET /Annunci | una rotta GET su /Annunci | niente: maiuscole e minuscole contano | 404 {"detail":"Not Found"} |
POST /annunci | una rotta POST su /annunci | il percorso c'è, ma solo per GET | 405 {"detail":"Method Not Allowed"}, con l'header allow: GET |
GET /annunci/ | una rotta GET su /annunci/ | niente, ma c'è /annunci senza la barra in fondo | 307 e l'header location: «vai lì» |
Il 307 è della famiglia 3xx, «vai altrove». Il corpo è vuoto: la strada giusta sta nell'header location. curl si ferma lì, a meno che tu non gli chieda di seguire il rimando con -L:
curl -i -L http://127.0.0.1:8000/annunci/HTTP/1.1 307 Temporary Redirect
date: Thu, 19 Nov 2026 16:08:09 GMT
server: uvicorn
content-length: 0
location: http://127.0.0.1:8000/annunci
HTTP/1.1 200 OK
date: Thu, 19 Nov 2026 16:08:09 GMT
server: uvicorn
content-length: 68
content-type: application/json
["Ascensore fermo fino alle 12","Binario 2: un treno ogni 5 minuti"]Il browser e il TestClient dei test seguono il rimando da soli: per loro la barra in fondo non fa differenza. curl no, e te lo fa vedere.
Cosa portiamo a casa. Il percorso deve essere uguale lettera per lettera, maiuscole comprese. Davanti a un 404 guarda il percorso; davanti a un 405, il verbo.
E · Dal 501 al verde
Nella stessa cartella, un secondo file: gli oggetti smarriti di Piazza Query. È fatto come gli esercizi della palestra, con la riga «da fare» e il suo test.
# smarriti.py
from fastapi import FastAPI, HTTPException
app = FastAPI(title="Gli oggetti smarriti di Piazza Query")
oggetti = ["ombrello blu", "guanto rosso", "sciarpa a righe"]
# Da fare: tutti gli oggetti smarriti, nell'ordine della lista.
# GET /smarriti -> 200 e ["ombrello blu", "guanto rosso", "sciarpa a righe"]
@app.get("/smarriti")
def lista_smarriti():
raise HTTPException(status_code=501, detail="Da fare: al posto di questa riga, il tuo codice")# test_smarriti.py
from fastapi.testclient import TestClient
import smarriti
client = TestClient(smarriti.app)
def test_gli_oggetti_smarriti():
risposta = client.get("/smarriti")
assert risposta.status_code == 200
assert risposta.json() == ["ombrello blu", "guanto rosso", "sciarpa a righe"]Il server può restare spento. Nel terminale (venv acceso):
pytest test_smarriti.py -vPrevedi: verde o rosso? Se è rosso, su quale riga del test si ferma, e con quali numeri?
Prevedi Scrivi su un foglio cosa ti aspetti, poi apri.
…
test_smarriti.py::test_gli_oggetti_smarriti FAILED [100%]
============================================= FAILURES =============================================
____________________________________ test_gli_oggetti_smarriti _____________________________________
def test_gli_oggetti_smarriti():
risposta = client.get("/smarriti")
> assert risposta.status_code == 200
E assert 501 == 200
E + where 501 = <Response [501 Not Implemented]>.status_code
test_smarriti.py:11: AssertionError
…Rosso, alla prima assert: la rotta ha risposto 501, perché c'è ancora la riga «da fare». Il test si ferma lì, e la seconda assert non la guarda nemmeno.
In italiano. Il test crea un client che parla con l'app del file smarriti.py, fa la richiesta GET /smarriti, poi controlla prima il codice e poi il corpo.
Passo per passo, le righe del test:
| Riga | Cosa fa |
|---|---|
client = TestClient(smarriti.app) | Un client che parla con l'app di smarriti.py direttamente: niente server, niente rete |
risposta = client.get("/smarriti") | La richiesta GET /smarriti, come curl http://127.0.0.1:8000/smarriti |
assert risposta.status_code == 200 | Il codice. Con la riga del 501 è 501: il test si ferma qui |
assert risposta.json() == [...] | Il corpo, tornato in Python: una lista di stringhe |
La correzione: al posto della riga del 501, il return della lista che c'è già.
@app.get("/smarriti")
def lista_smarriti():
return oggettiAdesso HTTPException non serve più: puoi togliere anche lui dall'import (VS Code lo mostra sbiadito). Di nuovo pytest test_smarriti.py -v:
…
test_smarriti.py::test_gli_oggetti_smarriti PASSED [100%]
======================================== 1 passed in 0.13s =========================================Cosa portiamo a casa. È il giro di ogni esercizio della palestra: rosso con il 501, al posto di quella riga il tuo codice, verde. E per lanciare i test il server non serve.
Pronto? Nella palestra ti aspettano quattro piccole API dell'officina del deposito, con i loro test.