API REST con FastAPI e Python: Guida Completa

FastAPI è un framework web moderno e veloce per la creazione di API con Python 3.7+ (anche se è consigliabile usare versioni più recenti). È basato su tipi standard di Python per la definizione dei dati, il che semplifica la validazione e la serializzazione. Alcune delle caratteristiche principali di FastAPI includono:

• Velocità: Basato su Starlette e Pydantic, offre prestazioni elevate.
• Facilità d'uso: Sintassi intuitiva e facile da imparare.
• Validazione dei dati: Utilizza Pydantic per la validazione automatica dei dati.
• Documentazione automatica: Genera automaticamente documentazione interattiva dell'API (Swagger UI e ReDoc).
• Supporto per tipi asincroni: Gestisce nativamente codice asincrono per prestazioni superiori.

Prima di iniziare, assicurati di avere installato Python 3.7+ e pip. Crea un ambiente virtuale per il tuo progetto:

python -m venv venv
source venv/bin/activate  # Linux/macOS
# venv\Scripts\activate  # Windows

Installa FastAPI e Uvicorn, un server ASGI (Asynchronous Server Gateway Interface) per eseguire FastAPI:

pip install fastapi uvicorn

Uvicorn è necessario per servire l'applicazione FastAPI.

Creiamo una semplice API che restituisce un messaggio di benvenuto. Crea un file chiamato main.py con il seguente contenuto:

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
async def read_root():
    """
    Endpoint principale che restituisce un messaggio di benvenuto.
    """
    return {"message": "Benvenuto nell'API FastAPI!"}

Questo codice definisce un'applicazione FastAPI e un endpoint GET alla radice (/). La funzione read_root è decorata con @app.get("/"), che indica che questa funzione gestirà le richieste GET all'endpoint principale. La funzione restituisce un dizionario Python, che FastAPI converte automaticamente in JSON. Per eseguire l'API, usa il comando uvicorn:

uvicorn main:app --reload

- main:app indica a Uvicorn di cercare un'istanza di FastAPI chiamata app nel file main.py. L'opzione --reload abilita il riavvio automatico del server quando si apportano modifiche al codice. Apri il tuo browser e vai all'indirizzo http://127.0.0.1:8000/. Dovresti vedere il messaggio JSON: {"message": "Benvenuto nell'API FastAPI!"}.

Ora, creiamo un endpoint che accetta un parametro nella URL. Modifica main.py come segue:

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
async def read_root():
    return {"message": "Benvenuto nell'API FastAPI!"}

@app.get("/items/{item_id}")
async def read_item(item_id: int, q: str = None):
    """
    Endpoint che restituisce un item specifico in base al suo ID.
    Accetta un parametro opzionale 'q' nella query string.
    """
    return {"item_id": item_id, "q": q}

In questo esempio, abbiamo aggiunto un nuovo endpoint /items/{item_id}. item_id: int specifica che item_id è un parametro di tipo intero. FastAPI eseguirà automaticamente la validazione del tipo. q: str = None definisce un parametro di query opzionale chiamato q con un valore predefinito di None. Riavvia il server Uvicorn (se non è in modalità --reload) e prova ad accedere a http://127.0.0.1:8000/items/123?q=test. Dovresti vedere un output simile a: {"item_id": 123, "q": "test"}. Se provi ad accedere a http://127.0.0.1:8000/items/abc, FastAPI restituirà un errore di validazione, poiché abc non è un intero valido.

sequenceDiagram
    participant Browser
    participant FastAPI
    Browser->>FastAPI: GET /items/123?q=test
    FastAPI->>FastAPI: Valida item_id (int) e q (str)
    FastAPI->>Browser: {"item_id": 123, "q": "test"}

Pydantic è una libreria Python per la validazione dei dati. FastAPI si integra perfettamente con Pydantic per definire schemi di dati e validare i dati in ingresso e in uscita. Creiamo un modello Pydantic per rappresentare un item. Modifica main.py come segue:

from fastapi import FastAPI
from pydantic import BaseModel

class Item(BaseModel):
    name: str
    description: str = None
    price: float
    tax: float = None

app = FastAPI()

@app.post("/items/")
async def create_item(item: Item):
    """
    Endpoint per creare un nuovo item.
    Utilizza un modello Pydantic per la validazione dei dati in ingresso.
    """
    item_dict = item.dict()
    if item.tax:
        price_with_tax = item.price + item.tax
        item_dict.update({"price_with_tax": price_with_tax})
    return item_dict

In questo esempio, abbiamo definito una classe Item che eredita da BaseModel. Questo definisce uno schema per i dati dell'item, inclusi i tipi di dati e i valori predefiniti. L'endpoint /items/ accetta una richiesta POST con un corpo JSON che corrisponde allo schema Item. FastAPI convaliderà automaticamente i dati in ingresso in base allo schema. Se i dati non sono validi, FastAPI restituirà un errore. Prova a inviare una richiesta POST a http://127.0.0.1:8000/items/ con il seguente corpo JSON:

{
    "name": "Test Item",
    "description": "This is a test item",
    "price": 10.0,
    "tax": 1.0
}

Dovresti ricevere una risposta simile a:

{
    "name": "Test Item",
    "description": "This is a test item",
    "price": 10.0,
    "tax": 1.0,
    "price_with_tax": 11.0
}

Se ometti un campo obbligatorio (ad esempio, price), FastAPI restituirà un errore di validazione.

È importante gestire gli errori in modo appropriato nelle API. FastAPI fornisce diversi meccanismi per la gestione degli errori, tra cui l'utilizzo di eccezioni e middleware personalizzati. Ecco un esempio di come gestire un'eccezione specifica:

from fastapi import FastAPI, HTTPException
from pydantic import BaseModel

class Item(BaseModel):
    name: str
    description: str = None
    price: float
    tax: float = None

app = FastAPI()

items = {}

@app.get("/items/{item_id}")
async def read_item(item_id: str):
    """
    Endpoint che restituisce un item specifico in base al suo ID.
    Gestisce l'eccezione HTTPException se l'item non viene trovato.
    """
    if item_id not in items:
        raise HTTPException(status_code=404, detail="Item not found")
    return items[item_id]

@app.post("/items/{item_id}")
async def create_item(item_id: str, item: Item):
    """
    Endpoint per creare un nuovo item con un ID specifico.
    """
    items[item_id] = item
    return {"item_id": item_id, **item.dict()}

In questo esempio, se l'item non viene trovato nell'endpoint read_item, viene sollevata un'eccezione HTTPException con codice di stato 404 e un messaggio di dettaglio. FastAPI gestirà automaticamente questa eccezione e restituirà una risposta JSON appropriata al client.

Una delle caratteristiche più potenti di FastAPI è la sua capacità di generare automaticamente la documentazione dell'API. FastAPI utilizza Swagger UI e ReDoc per fornire una documentazione interattiva dell'API. Per accedere alla documentazione Swagger UI, apri il tuo browser e vai all'indirizzo http://127.0.0.1:8000/docs. Dovresti vedere un'interfaccia utente interattiva che ti consente di esplorare gli endpoint dell'API, inviare richieste di prova e visualizzare le risposte. Per accedere alla documentazione ReDoc, vai all'indirizzo http://127.0.0.1:8000/redoc. ReDoc fornisce una documentazione dell'API più pulita e orientata alla documentazione.

flowchart LR
    A[Codice FastAPI] --> B{Documentazione Automatica};
    B --> C[Swagger UI];
    B --> D[ReDoc];
    C --> E[Interfaccia Interattiva];
    D --> F[Documentazione Pulita];