Vai al contenuto
code-to-code

Apro l'indice…

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

HTTP e API4. Il primo serverp. 92

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:

  1. Prevedi: leggi il codice e la richiesta, e scrivi su un foglio cosa risponde il server. Prima di aprire la risposta.
  2. In italiano: cosa fa il codice, a parole.
  3. Passo per passo: cosa succede alla richiesta, un pezzo alla volta.
  4. 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:

Python
# 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:

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 al return senza 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.

  1. Creo l'applicazione, con il suo nome.
  2. Collego la funzione saluto alle richieste GET sul percorso /.
  3. La funzione restituisce un dizionario con due chiavi.

Il disegno.

inizio curl GET / passo uvicorn riceve la richiesta passo FastAPI cerca la rotta GET / passo saluto() restituisce il dizionario passo FastAPI lo trasforma in JSON mostra curl stampa 200 e il JSON finecurl GET /uvicorn riceve la richiestaFastAPI cerca la rotta GET /saluto() restituisce ildizionarioFastAPI lo trasforma in JSONmostra curl stampa 200 e ilJSONfine
Il viaggio di GET /

Passo per passo.

PassoDoveCosa succede
1secondo terminalecurl manda GET / HTTP/1.1 al tuo computer, porta 8000
2primo terminaleuvicorn riceve la richiesta e la passa a FastAPI
3FastAPIcerca una rotta con il verbo GET e il percorso /: è saluto
4bacheca.pysaluto() restituisce il dizionario
5FastAPItrasforma il dizionario in testo JSON e aggiunge content-type: application/json
6secondo terminalecurl stampa la risposta: 200 e il JSON
7primo terminaleil 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:

Python
@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",
    }
Terminale
curl -s http://127.0.0.1:8000/stazione

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

ChiaveIn PythonNel JSON
"nome""Piazza Query""Piazza Query"
"aperta"Truetrue
"ascensore_funziona"Falsefalse
"binari"(1, 2), una tupla[1,2]: il JSON non ha tuple, solo liste
"gradi"21.521.5
"annuncio_urgente"Nonenull
"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ì:

Python
annunci = ["Ascensore fermo fino alle 12", "Binario 2: un treno ogni 5 minuti"]


@app.get("/annunci")
def lista_annunci():
    print(annunci)
Terminale
curl -i http://127.0.0.1:8000/annunci

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

null

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

La 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 listanel terminale del server, a tenella risposta, al client
Cosa restituisce la funzioneNonela lista
Il corpo della rispostanull["Ascensore fermo fino alle 12","Binario 2: un treno ogni 5 minuti"]
Il codice200200

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:

Terminale
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 Redirect

La 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/annunci

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

inizio arriva una richiesta se c'è una rotta con verbo e percorso sì: restituisci 200 e il return della funzione se c'è lo stesso percorso senza la barra sì: restituisci 307 e location se il percorso c'è, con un altro verbo sì: errore 405 Method Not Allowed errore 404 Not Foundarriva una richiestac'è una rotta converbo e percorsorestituisci 200 e il returndella funzionec'è lo stessopercorso senza labarrarestituisci 307 e locationil percorso c'è, conun altro verbo405 Method Not Allowed404 Not Foundnosìnosìnosì
Dove va a finire una richiesta

Passo per passo, richiesta per richiesta:

RichiestaFastAPI cercaTrovaRisponde
GET /annunciuna rotta GET su /annuncilista_annunci200 e la lista
GET /annunciouna rotta GET su /annuncioniente: manca una lettera404 {"detail":"Not Found"}
GET /Annunciuna rotta GET su /Annunciniente: maiuscole e minuscole contano404 {"detail":"Not Found"}
POST /annunciuna rotta POST su /annunciil percorso c'è, ma solo per GET405 {"detail":"Method Not Allowed"}, con l'header allow: GET
GET /annunci/una rotta GET su /annunci/niente, ma c'è /annunci senza la barra in fondo307 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:

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

Python
# 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")
Python
# 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):

Terminale
pytest test_smarriti.py -v

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

RigaCosa 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 == 200Il 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à.

Python
@app.get("/smarriti")
def lista_smarriti():
    return oggetti

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