Il primo server
Dall'altra parte del filo, una funzione Python che risponde
- 12 minuti di lettura
Nei primi tre capitoli hai fatto domande a InfoMenta. Il server l'aveva scritto qualcun altro: tu stavi dalla parte del client. Adesso passi dall'altra parte del filo, e il server lo scrivi tu.
Ivo Brambati, il manutentore del deposito, è stufo dei foglietti attaccati al muro dell'officina. Vuole una lavagna da consultare con il browser, o con curl: un server suo. Con FastAPI un server è un file Python, e il primo è lungo così:
# officina.py
from fastapi import FastAPI
app = FastAPI(title="L'officina del deposito")
@app.get("/")
def benvenuto():
return {"messaggio": "L'officina del deposito è aperta"}Quando qualcuno chiede GET /, FastAPI chiama benvenuto() e manda indietro, in JSON, quello che la funzione restituisce. Tutto il capitolo è questa frase.
Se vuoi provarlo mentre leggi: scarica lo zip dalla palestra, prepara il venv come dice il suo README.md, e crea officina.py nella cartella dello zip, accanto a palestra/.
Installare FastAPI
FastAPI non fa parte di Python: si installa con pip, dentro il venv.
pip install "fastapi[standard]"| Pezzo | Cosa vuol dire |
|---|---|
fastapi | La libreria per scrivere API |
[standard] | Non è una versione: è un pacchetto di extra. Porta il comando fastapi e uvicorn, il programma che resta acceso ad ascoltare le richieste. Senza, fastapi dev non esiste |
| le virgolette | Su Mac le quadre hanno un significato speciale per il terminale: senza virgolette arriva zsh: no matches found: fastapi[standard] |
Negli zip di questo libro FastAPI è già scritto nel requirements.txt: basta pip install -r requirements.txt, come in Il venv e pip.
Riga per riga
| Riga | Cosa fa |
|---|---|
from fastapi import FastAPI | Prende FastAPI dalla libreria, come ogni import |
app = FastAPI(title="…") | Crea l'applicazione: l'oggetto che riceve le richieste. Il title è il nome che vedrai nella documentazione. Si chiama app per abitudine: con questo nome la cercano fastapi dev e i test |
@app.get("/") | Il decoratore: la riga con la @ si appoggia sulla funzione subito sotto e la collega alle richieste GET sul percorso / |
def benvenuto(): | Una funzione normale. Il nome lo scegli tu |
return … | Quello che restituisci è il corpo della risposta. FastAPI lo trasforma in JSON |
Decoratore più funzione fanno una rotta: un verbo, un percorso e la funzione che risponde. Un file può avere tante rotte, una sotto l'altra.
Accendere il server
Il server è un programma che resta acceso e aspetta. Ti servono due terminali, tutti e due nella cartella dello zip e con il venv acceso (su Windows: due terminali di Ubuntu).
Nel primo terminale (il server):
fastapi dev officina.py ⚡️ Starting FastAPI in development mode
🐍 Using import string: officina:app
🌐 Server started at http://127.0.0.1:8000
Documentation at http://127.0.0.1:8000/docs
Logs:
INFO: Will watch for changes in these directories: ['~/corso/http-primo-server']
INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
INFO: Started reloader process [35147] using WatchFiles
INFO: Started server process [35159]
INFO: Waiting for application startup.
INFO: Application startup complete.| Riga | Vuol dire |
|---|---|
Using import string: officina:app | Ha trovato il file officina.py e, dentro, l'oggetto app |
Server started at http://127.0.0.1:8000 | Ascolta su questo indirizzo: 127.0.0.1 è il tuo computer, 8000 la porta. I pezzi di un indirizzo sono in Il viaggio di una richiesta |
Documentation at …/docs | La documentazione, scritta da sola: la vediamo più sotto |
Will watch for changes | dev vuol dire «sviluppo»: ogni volta che salvi un file della cartella, il server si riavvia da solo |
Application startup complete. | Pronto: puoi fare domande |
Da qui il terminale resta occupato: ogni richiesta che arriva compare lì. Per spegnere il server: Ctrl+C.
La prima domanda
Nel secondo terminale (venv acceso):
curl -i http://127.0.0.1:8000/HTTP/1.1 200 OK
date: Thu, 19 Nov 2026 16:02:21 GMT
server: uvicorn
content-length: 49
content-type: application/json
{"messaggio":"L'officina del deposito è aperta"}Nel terminale del server compare:
INFO: 127.0.0.1:59988 - "GET / HTTP/1.1" 200 OKÈ la stessa richiesta, vista dall'altra parte: chi l'ha fatta (127.0.0.1, più un numero di porta del client che cambia ogni volta), la riga di richiesta (GET / HTTP/1.1) e il codice della risposta. Lo stesso indirizzo nel browser, http://127.0.0.1:8000/, mostra lo stesso JSON.
Il viaggio, disegnato:
CLIENT (curl) SERVER (uvicorn e FastAPI) officina.py
│ │ │
│ GET / │ │
│ ────────────────────────────▶ │ c'è una rotta GET su "/"? │
│ │ sì, è benvenuto() ─────────────▶ │
│ │ │ return {"messaggio": "…"}
│ │ ◀──────────────────────────────── │ un dizionario Python
│ │ dal dizionario al testo JSON │
│ 200 OK │ │
│ {"messaggio":"…"} │ │
│ ◀──────────────────────────── │ │Dal dizionario al JSON
La funzione restituisce valori Python. Sul filo viaggia testo JSON. In mezzo c'è FastAPI, che traduce così:
| In Python restituisci | Nel JSON arriva |
|---|---|
un dizionario, {"aperta": True} | un oggetto, {"aperta":true} |
una lista ["T09", "M16"], o una tupla ("T09", "M16") | una lista, ["T09","M16"] |
una stringa, "T09" | "T09", sempre tra virgolette doppie |
un numero, 4 o 18.5 | 4, 18.5 |
True, False | true, false |
None | null |
È la tabella del JSON di Moduli e file, letta da destra a sinistra: il json.dumps lo fa FastAPI per te.
Ivo aggiunge a officina.py una seconda rotta, e salva:
@app.get("/stato")
def stato():
return {
"aperta": True,
"treni_dentro": ("T09", "M16"),
"ispezione": None,
"temperatura": 18.5,
}Il disegno.
Appena salva, nel terminale del server:
WARNING: WatchFiles detected changes in 'officina.py'. Reloading...
INFO: Shutting down
INFO: Waiting for application shutdown.
INFO: Application shutdown complete.
INFO: Finished server process [35159]
INFO: Started server process [35181]
INFO: Waiting for application startup.
INFO: Application startup complete.Il server si è spento e riacceso da solo, con la rotta nuova. Nel secondo terminale:
curl -s http://127.0.0.1:8000/stato{"aperta":true,"treni_dentro":["T09","M16"],"ispezione":null,"temperatura":18.5}La documentazione si scrive da sola
Con il server acceso, apri nel browser http://127.0.0.1:8000/docs. In alto c'è il title dell'app; sotto, una riga per ogni rotta, con il verbo e il percorso. Il nome della funzione diventa il titolo della rotta: benvenuto diventa «Benvenuto».
Clic su una rotta, poi Try it out, poi Execute: /docs fa la richiesta per te e mostra il comando curl che ha usato, il codice (Code) e il corpo (Response body). È curl, con i bottoni.
| Indirizzo | Cos'è |
|---|---|
/docs | La documentazione da provare: ogni rotta, con Try it out |
/redoc | La stessa documentazione, in versione da leggere |
/openapi.json | Il contratto in JSON: l'elenco delle rotte. Le altre due pagine nascono da qui |
curl -s http://127.0.0.1:8000/openapi.json | python3 -m json.tool{
"openapi": "3.1.0",
"info": {
"title": "L'officina del deposito",
"version": "0.1.0"
},
"paths": {
"/": {
"get": {
"summary": "Benvenuto",
"operationId": "benvenuto__get",
…
"/stato": {
"get": {
"summary": "Stato",
"operationId": "stato_stato_get",
…
}Nessuno ha scritto queste pagine: FastAPI le ricava dai decoratori e dalle funzioni. Il contratto torna nell'ultimo capitolo del libro, Il contratto.
Quello che FastAPI fa da solo
Ivo ha scritto due rotte, GET / e GET /stato. A tutto il resto risponde FastAPI, senza una riga sua.
Un percorso che non ha una rotta (a /stat manca una lettera):
curl -i http://127.0.0.1:8000/statHTTP/1.1 404 Not Found
date: Thu, 19 Nov 2026 16:02:25 GMT
server: uvicorn
content-length: 22
content-type: application/json
{"detail":"Not Found"}Un percorso che c'è, con un verbo che non c'è (una POST su /):
curl -i -X POST http://127.0.0.1:8000/HTTP/1.1 405 Method Not Allowed
date: Thu, 19 Nov 2026 16:02:25 GMT
server: uvicorn
allow: GET
content-length: 31
content-type: application/json
{"detail":"Method Not Allowed"}L'header allow: GET dice quali verbi ci sono. I due codici li conosci da Verbi e codici: 404 «qui non c'è niente», 405 «c'è, ma non con questo verbo». Il 404 scritto da te, quello di un treno che non esiste, arriva in CRUD su un dizionario.
La riga «da fare» e i test
Negli esercizi di questo libro, una rotta da completare ha già il decoratore e il def, e al posto del codice una riga sola:
from fastapi import FastAPI, HTTPException
# … il resto del file …
@app.get("/")
def benvenuto():
raise HTTPException(status_code=501, detail="Da fare: al posto di questa riga, il tuo codice")raise lo conosci da try, except, raise: ferma la funzione. HTTPException è un errore di FastAPI che diventa una risposta, con il codice che gli dai: qui 501, Not Implemented, «non ancora fatto». Accendi il primo esercizio della palestra, fastapi dev palestra/lavagna.py, e chiedi /:
curl -i http://127.0.0.1:8000/HTTP/1.1 501 Not Implemented
date: Thu, 19 Nov 2026 16:02:36 GMT
server: uvicorn
content-length: 60
content-type: application/json
{"detail":"Da fare: al posto di questa riga, il tuo codice"}Tu cancelli quella riga e al suo posto scrivi il tuo codice.
I test, invece, non accendono nessun server. Usano il TestClient che hai già incontrato in Fare richieste: un client che parla con l'app direttamente, senza passare dalla rete.
from fastapi.testclient import TestClient
import lavagna
client = TestClient(lavagna.app)
def test_l_indirizzo_principale_risponde():
risposta = client.get("/")
assert risposta.status_code == 200, "GET / deve rispondere 200. C'è ancora la riga del 501?"client.get("/") è la stessa richiesta di curl http://127.0.0.1:8000/. risposta.status_code è il codice, risposta.json() è il corpo tornato in Python, come con httpx. Con la riga del 501 ancora al suo posto, pytest dice:
…
E AssertionError: GET / deve rispondere 200. C'è ancora la riga del 501?
E assert 501 == 200
E + where 501 = <Response [501 Not Implemented]>.status_code
…Le mosse
| Vuoi | Scrivi |
|---|---|
| L'applicazione | app = FastAPI(title="…") |
| Rispondere alle GET su un percorso | @app.get("/percorso"), sopra un def |
| Rispondere con un oggetto JSON | return {"chiave": valore} |
| Rispondere con una lista JSON | return una_lista |
| Accendere il server | fastapi dev palestra/lavagna.py (dalla cartella dello zip) |
| Spegnerlo | Ctrl+C, nel suo terminale |
| Provare a mano | /docs, curl, il browser |
| Provare con i test | TestClient(lavagna.app), poi pytest |
E dopo
Le rotte di questo capitolo non ricevono niente: GET /stato risponde sempre allo stesso modo, con i dati scritti nel file. Nel prossimo capitolo, La forma della chiamata, le rotte ricevono un pezzo di percorso (/treni/3), una domanda nella query (?tipo=tram), un corpo in JSON.
E i dati scritti nel file vivono nella memoria del server: a ogni riavvio tornano com'erano nel file. Per conservarli davvero serve un database: lo vedrai in Perché un database.
Ricorda
- Un server FastAPI è un file Python:
app = FastAPI()e una funzione per ogni rotta. @app.get("/percorso")collega la funzione sotto alle richieste GET su quel percorso.- Il
returnè la risposta: FastAPI la trasforma in JSON (Truediventatrue,Nonediventanull). Tu scrivi Python, non JSON. fastapi dev file.pyaccende e riavvia a ogni salvataggio,Ctrl+Cspegne,/docsprova ogni rotta.- Percorso che non c'è: 404. Verbo che non c'è: 405. Li dà FastAPI da solo.