Come definisci le route (operazioni di path)?

Question

Accepted Answer

In FastAPI, un'**operazione di path** è una route — una funzione decorata con un decoratore di metodo HTTP (`@app.get`, `@app.post`, ecc.) che gestisce le richieste a un path. Il valore di ritorno della funzione è automaticamente serializzato in JSON.

## Definire route per ogni metodo HTTP

```python
from fastapi import FastAPI
app = FastAPI()

@app.get("/items")                # GET /items
def list_items():
    return [{"id": 1}, {"id": 2}]  # dict/list → automatically JSON-serialized

@app.get("/items/{item_id}")      # GET /items/5 — path parameter
def get_item(item_id: int):        # type hint converts "5" → int (and validates)
    return {"id": item_id}

@app.post("/items")               # POST /items
def create_item(item: Item):
    return item

@app.put("/items/{item_id}")      # PUT, PATCH, DELETE work the same way
@app.delete("/items/{item_id}")
def delete_item(item_id: int):
    return {"deleted": item_id}
```

Ogni decoratore mappa un metodo HTTP + path a un handler. Il nome della funzione è tuo; il decoratore definisce la route. I dict/list/modelli Pydantic ritornati sono serializzati in JSON automaticamente — niente `json.dumps` manuale.

## L'ordine è importante per i path sovrapposti

```python
@app.get("/users/me")            # ✅ specific route FIRST
def read_me(): ...
@app.get("/users/{user_id}")     # dynamic AFTER — else "me" matches {user_id}
def read_user(user_id: int): ...
```

FastAPI abbina le route in ordine di dichiarazione, quindi metti i path statici prima di quelli dinamici.

## Metadati dell'operazione (alimentano la documentazione)

```python
@app.get("/items", tags=["items"], summary="List items", status_code=200)
def list_items(): ...
```

I parametri del decoratore (`tags`, `summary`, `status_code`, `response_model`) configurano il comportamento e arricchiscono la documentazione auto-generata.

## Perché è importante

Le operazioni di path sono il fondamento di ogni applicazione FastAPI — definiscono gli endpoint della tua API e come le richieste vengono gestite.

Comprendere il pattern decoratore-per-metodo-HTTP, che i valori di ritorno sono automaticamente serializzati in JSON (niente boilerplate), che i type hint sui parametri guidano la conversione e la validazione, e che l'ordine delle route è importante per i path sovrapposti è una conoscenza essenziale di ogni giorno per costruire qualsiasi endpoint.

I metadati del decoratore alimentano anche la documentazione automatica di FastAPI, collegando direttamente le route alla documentazione.

Questa è la prima e più fondamentale cosa da padroneggiare in FastAPI.