Cos'è FastAPI? Guida pratica per costruire API

FastAPI in un minuto: la definizione semplice

FastAPI è un framework Python per costruire API web rapidamente, con codice chiaro e documentazione automatica. Scrivi piccole funzioni (chiamate “endpoint”) che dichiarano quali dati accetta la tua API e cosa restituisce, e FastAPI si occupa dell'infrastruttura web—routing, validazione e produzione di risposte JSON.

Cos'è un'API? Un esempio semplice

Un'API è un insieme di URL che permette a un pezzo di software di parlare con un altro.

Per esempio, un'app meteo sul telefono potrebbe chiamare un URL tipo GET /weather?city=Berlin. Il server risponde con dati strutturati (di solito JSON), come temperatura e previsione. L'app non ha bisogno di accesso diretto al database del server—chiede semplicemente all'API e mostra il risultato.

FastAPI ti aiuta a creare quegli URL e quelle risposte in Python.

Per chi è FastAPI?

• Principianti che vogliono un modo moderno e guidato per costruire API senza scrivere molto boilerplate.
• Sviluppatori soli che devono muoversi velocemente mantenendo il codice leggibile.
• Team che costruiscono servizi di produzione che beneficiano di forte validazione, contratti coerenti e ottima documentazione.

Non è necessario essere esperti di async per iniziare; puoi scrivere endpoint semplici e adottare pattern più avanzati man mano che cresci.

Cosa imparerai in questa guida

• Cosa rende FastAPI diverso dalle altre opzioni Python per le API
• Come funzionano richieste e risposte (e cosa significa davvero “async”)
• Come funziona la validazione dei dati con Pydantic
• Come FastAPI genera documentazione OpenAPI (Swagger UI e ReDoc)
• Come strutturare app con dependency, sicurezza, test e nozioni di base sul deploy

Perché FastAPI è diventato popolare

FastAPI è decollato rapidamente perché elimina molte delle frizioni quotidiane che si incontrano costruendo API in Python.

Affronta i problemi comuni delle API

I progetti API tradizionali spesso iniziano con una configurazione lenta e tanto “plumbing”:

• Scrivere manualmente (e mantenere sincronizzati) parsing delle richieste, validazione e messaggi di errore
• Contratti API poco chiari—cosa accetta e cosa restituisce esattamente un endpoint?
• Documentazione che resta indietro rispetto al codice, specialmente con team in crescita

Le funzionalità principali di FastAPI mirano direttamente a questi problemi, così i team passano più tempo a progettare endpoint e meno a combattere il boilerplate del framework.

I type hint trasformano il codice in un contratto

FastAPI fa grande uso dei type hint di Python. Quando dichiari che un campo è un int, opzionale o una lista di qualcosa, FastAPI usa quelle informazioni per validare gli input e modellare gli output.

Questo riduce gli errori da “stringly-typed” (per esempio trattare un ID come testo in un punto e come numero in un altro) e incoraggia comportamenti coerenti degli endpoint. È sempre Python, ma con aspettative più chiare incise nelle firme delle funzioni.

Documentazione automatica accelera il lavoro del team

Poiché lo schema dell'API viene ricavato dal codice, FastAPI può generare documentazione interattiva automaticamente (OpenAPI + Swagger UI/ReDoc). Questo è importante per la collaborazione: frontend, QA e integratori possono esplorare gli endpoint, provare richieste e vedere i modelli esatti senza aspettare una documentazione separata.

Popolare, ma non una bacchetta magica

FastAPI non risolverà un'API progettata male. Serve comunque una buona denominazione, versioning, gestione degli errori e decisioni di sicurezza. Ciò che offre è un percorso più pulito dall'“idea” a un'“API ben definita” con meno sorprese.

Concetti chiave da conoscere

FastAPI sembra semplice una volta che capisci alcune idee fondamentali su cui si basa. Non serve memorizzare gli interni—basta riconoscere le parti che userai ogni giorno.

FastAPI è un framework

Un framework è un insieme di strumenti e convenzioni per costruire un'API senza partire da zero. FastAPI fornisce il “plumbing” per i compiti comuni delle API: definire endpoint, leggere input, restituire output, gestire errori e organizzare il codice in modo mantenibile.

Routing: come si definiscono gli endpoint

Routing è come mappi un URL e un metodo HTTP a un pezzo di codice Python.

Per esempio, potresti mappare GET /users a “lista utenti” e POST /users a “crea un utente”. In FastAPI, definisci tipicamente le rotte con decorator come @app.get(...) e @app.post(...), rendendo facile vedere cosa offre la tua API a colpo d'occhio.

Richieste e risposte

Ogni chiamata API è una request (quello che il client invia) e una response (quello che il server restituisce).

FastAPI ti aiuta a:

• Leggere dati da path (/users/{id}), query string (?page=2), header e body della richiesta
• Restituire risposte JSON strutturate con i corretti status code (come 200, 201, 404)

ASGI (livello alto)

FastAPI gira su ASGI, uno standard moderno per server web Python. Nella pratica significa che FastAPI è progettato per gestire molte connessioni in modo efficiente e può supportare funzionalità come connessioni a lunga durata (es. WebSockets) senza che tu debba gestire il networking a basso livello.

Type hint: più di una semplice annotazione

I type hint di Python (come str, int, list[Item]) non sono solo documentazione in FastAPI—sono un input chiave. FastAPI li usa per capire quali dati aspettarsi, convertire i valori in arrivo nei tipi corretti e produrre API più chiare e prevedibili.

Modelli Pydantic per la validazione

I modelli Pydantic ti permettono di definire la forma dei dati (campi, tipi, valori opzionali) in un solo posto. FastAPI usa questi modelli per validare il JSON in ingresso, rifiutare input non validi con messaggi di errore utili e serializzare l'output in modo coerente—così la tua API si comporta in modo affidabile anche quando i client inviano dati disordinati.

Come FastAPI gestisce richieste e risposte

Le app FastAPI si basano su endpoint: un percorso URL più un metodo HTTP. Pensa a un endpoint come "cosa chiede il client" e "come lo chiede". Per esempio, un client potrebbe GET /users per elencare utenti, o POST /users per crearne uno.

Endpoint = path + method

Un path è la rotta e il method è l'azione:

• GET /products → recuperare dati
• POST /products → inviare dati per creare qualcosa
• PUT /products/123 → sostituire/aggiornare qualcosa
• DELETE /products/123 → rimuovere qualcosa

Path parameter vs query parameter

FastAPI separa i dati che fanno parte del path dai dati che sono filtri opzionali sulla richiesta.

• Path parameter: incluso nella struttura dell'URL.
  • Esempio: GET /users/42 → 42 è l'ID utente.
• Query parameter: aggiunto dopo ? e tipicamente opzionale.
  • Esempio: GET /users?limit=10&active=true → limit e active controllano come vengono restituiti i risultati.

Request body per payload JSON

Quando un client invia dati strutturati (di solito JSON), questi vanno nel body della richiesta, più spesso con POST o PUT.

Esempio: POST /orders con JSON come { "item_id": 3, "quantity": 2 }.

Response model e output coerente

FastAPI può restituire oggetti Python semplici (come dict), ma dà il meglio quando definisci un response model. Quel modello funge da contratto: i campi sono coerenti, i dati extra possono essere filtrati e i tipi vengono applicati. Il risultato sono API più pulite—i client sanno cosa aspettarsi e si evitano risposte “a sorpresa” che rompono le integrazioni.

Async in FastAPI: cos'è e quando aiuta

“Async” (abbreviazione di asynchronous) è un modo per la tua API di gestire molte richieste in modo efficiente quando gran parte del tempo è spesa in attesa.

Un'analogia quotidiana: aspettare l'I/O

Immagina un barista che prende ordini. Se dovesse stare fermo a non fare nulla mentre la macchina del caffè gira, servirebbe meno clienti. Un approccio migliore è: avvia il caffè, poi prendi il prossimo ordine mentre la macchina lavora.

L'async funziona così. La tua app FastAPI può avviare un'operazione che aspetta qualcosa di lento—come una richiesta di rete o una query al database—e mentre aspetta, può passare a gestire altre richieste in arrivo.

Quando l'async è più utile

L'async è utile quando la tua API fa molto lavoro di I/O (input/output)—operazioni che passano tempo in attesa più che a “elaborare”. Esempi comuni:

• Chiamare un database (soprattutto su rete)
• Chiamare servizi esterni (provider di pagamento, mappe, API email)
• Leggere/scrivere file o parlare con object storage

Se i tuoi endpoint passano spesso tempo in queste operazioni, l'async può migliorare il throughput e ridurre il rischio che le richieste si accumulino sotto carico.

Quando l'async conta poco

L'async non è una bacchetta magica per tutto. Se il tuo endpoint è principalmente CPU-bound—ad es. ridimensionare immagini grandi, eseguire calcoli di data science o cifrare payload pesanti—l'async non accelererà l'elaborazione stessa. In quei casi servono tattiche diverse (background worker, process pool o scalare orizzontalmente).

Buone notizie: il codice sync funziona ancora

Non devi riscrivere tutto per usare FastAPI. Puoi scrivere funzioni di route normali (sincrone) e FastAPI le eseguirà correttamente. Molti progetti mescolano entrambi gli stili: mantieni semplici endpoint sincroni e usa async def dove aiuta chiaramente (di solito intorno a chiamate DB o HTTP esterne).

Validazione e serializzazione con Pydantic

La validazione è il checkpoint tra il mondo esterno e il tuo codice. Quando un'API accetta input (body JSON, query params, path params), vuoi essere sicuro che sia completo, del tipo corretto e entro limiti ragionevoli—prima di scrivere su un DB, chiamare un altro servizio o attivare la logica di business.

FastAPI si affida ai modelli Pydantic per questo. Descrivi cosa significa “dati buoni” una sola volta e FastAPI automaticamente:

• respinge gli input errati in anticipo
• converte i tipi quando possibile (per esempio trasformando "42" in intero)
• restituisce risposte JSON coerenti (serializzazione)

Catturare input errato presto (con errori chiari)

Se un client invia dati con forma sbagliata, FastAPI risponde con 422 Unprocessable Entity e un payload di errore strutturato che indica il campo esatto e il motivo. Questo facilita il lavoro degli sviluppatori client per correggere le richieste rapidamente, senza dover indovinare.

Esempi di validazione comuni

Ecco un piccolo modello che mostra campi richiesti, tipi, vincoli min/max e formati:

from pydantic import BaseModel, EmailStr, Field

class UserCreate(BaseModel):
    email: EmailStr
    age: int = Field(ge=13, le=120)
    username: str = Field(min_length=3, max_length=20)

• Campi obbligatori: email deve essere presente.
• Tipi: age deve essere un intero.
• Min/max: age è limitato a 13–120.
• Formati: EmailStr impone una forma valida di email.

Serializzazione: restituire JSON pulito e prevedibile

Gli stessi modelli possono modellare l'output, così le risposte dell'API non filtrano accidentalmente campi interni. Restituisci oggetti Python; FastAPI (tramite Pydantic) li converte in JSON con i nomi dei campi e i tipi corretti.

Documentazione API automatica: OpenAPI, Swagger UI, ReDoc

Una delle caratteristiche più pratiche di FastAPI è che genera la documentazione dell'API automaticamente—basata sul codice che hai già scritto.

OpenAPI: un contratto leggibile da macchine

OpenAPI è uno standard per descrivere un'API in formato strutturato (di solito JSON). Pensalo come un “contratto” che specifica:

• quali endpoint esistono (es. GET /users/{id})
• quali parametri accettano
• come deve essere il body della richiesta
• quali risposte ed errori aspettarsi

Poiché è leggibile da strumenti, può essere usato per generare client, validare richieste e mantenere i team allineati.

Swagger UI e ReDoc: docs interattive pronte all'uso

FastAPI serve automaticamente due pagine di documentazione umano-friendly:

• Swagger UI (interattiva): prova gli endpoint direttamente nel browser, compila i parametri, invia richieste e vedi le risposte.
• ReDoc (leggibile): una pagina di riferimento pulita.

In un progetto FastAPI tipico li trovi su:

• /docs (Swagger UI)
• /redoc (ReDoc)

Documentazione che rimane sincronizzata con il codice

Quando cambi path parameter, request model, response model o regole di validazione, lo schema OpenAPI (e le pagine di docs) si aggiornano automaticamente. Nessun passo separato di “manutenzione docs”.

Perché questo accelera frontend e QA

• Frontend può esplorare gli endpoint subito e capire i campi richiesti senza aspettare una specifica manuale.
• QA può testare casi limite rapidamente (campi mancanti, tipi sbagliati) e vedere risposte d'errore esatte.
• Tutti condividono la stessa fonte di verità: l'API in esecuzione e il suo contratto OpenAPI.

La tua prima app FastAPI (panoramica concettuale)

Un'app FastAPI può essere piccola e comunque sentirsi “reale”. Definisci un oggetto Python chiamato app, aggiungi un paio di route e avvia un server locale per provarlo nel browser.

1) Un endpoint minimale “hello”

Ecco l'esempio più piccolo utile:

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
def read_root():
    return {"message": "Hello, FastAPI"}

Questo è tutto: una rotta (GET /) che restituisce JSON.

2) Aggiungi semplici endpoint create/read (in memoria)

Per farlo sembrare una vera API, memorizziamo gli item in una lista. Non è un database—i dati si resettano al riavvio del server—ma è perfetto per imparare.

from fastapi import FastAPI

app = FastAPI()
items = []

@app.post("/items")
def create_item(name: str):
    item = {"id": len(items) + 1, "name": name}
    items.append(item)
    return item

@app.get("/items")
def list_items():
    return items

Ora puoi:

• POST /items?name=Coffee per aggiungere un elemento
• GET /items per recuperare la lista

3) Tipica struttura di progetto minimale

Una struttura di partenza comune è:

• main.py (crea app e le route)
• requirements.txt o pyproject.toml (dipendenze)

4) Avvio locale (concettuale)

Di solito:

1. Installa le dipendenze (FastAPI + un server ASGI come Uvicorn)
2. Avvia il server di sviluppo (per esempio: uvicorn main:app --reload)
3. Apri http://127.0.0.1:8000 e prova gli endpoint

Dependency e blocchi riutilizzabili

Le “dependency” di FastAPI sono input condivisi di cui i tuoi endpoint hanno bisogno—cose come la sessione del database, l'utente corrente, le impostazioni dell'app o parametri di query comuni. Invece di ricreare o parsare tutto in ogni route, le definisci una volta e FastAPI le fornisce dove servono.

Cos'è una dependency (in parole semplici)

Una dependency è di solito una funzione (o classe) che restituisce un valore che il tuo endpoint può usare. FastAPI la chiamerà per te, capirà di cosa ha bisogno (in base ai suoi parametri) e inietterà il risultato nella funzione dell'operazione di percorso.

Questo è spesso chiamato dependency injection, ma puoi pensarci come: “dichiara ciò di cui hai bisogno e FastAPI lo collega”.

Perché riduce la ripetizione

Senza dependency, potresti:

• Aprire/chiudere connessioni al DB in ogni endpoint
• Ripetere controlli di autenticazione ovunque
• Riparsare gli stessi parametri di paginazione in molte rotte

Con le dependency centralizzi quella logica. Se poi cambi come creare una sessione DB o come caricare l'utente corrente, aggiorni un solo posto—non dozzine di endpoint.

Esempi comuni di dependency

• Sessione DB: creare una sessione per richiesta e chiuderla in modo affidabile.
• Settings/config: fornire impostazioni basate sull'ambiente senza passarle manualmente.
• Paginazione: riutilizzare parsing e validazione di page/limit.
• Auth user: ottenere l'utente corrente da un token e applicare permessi.

Come le dependency entrano negli endpoint

Ecco il pattern concettuale che vedrai in molte app FastAPI:

from fastapi import Depends, FastAPI

app = FastAPI()

def get_settings():
    return {"items_per_page": 20}

@app.get("/items")
def list_items(settings=Depends(get_settings)):
    return {"limit": settings["items_per_page"]}

Dichiari la dependency con Depends(...) e FastAPI passa il suo risultato nel parametro dell'endpoint. Lo stesso approccio funziona per building block più complessi (come get_db() o get_current_user()), aiutando il codice a rimanere più pulito man mano che l'API cresce.

Nozioni di base sulla sicurezza: autenticazione e autorizzazione

FastAPI non “autoprotegge” l'API—scegli lo schema e integralo negli endpoint. La buona notizia è che FastAPI fornisce mattoni (specialmente tramite il sistema di dependency) che rendono semplici i pattern di sicurezza comuni.

Autenticazione vs autorizzazione

Autenticazione risponde: “Chi sei?” Autorizzazione risponde: “Cosa puoi fare?”

Esempio: un utente può essere autenticato (login/token valido) ma non autorizzato ad accedere a una rotta solo per admin.

Approcci comuni di autenticazione (alto livello)

• API key: semplice per accesso service-to-service. Di solito inviata via header (es. X-API-Key). Gestire rotazione e revoca.
• OAuth2: standard per accessi delegati; comune per “Sign in with …” o per separare l'autenticazione dall'API.
• JWT (JSON Web Tokens): usati come bearer token. Comodi per API senza stato, ma bisogna gestire scadenze, chiavi di firma e strategia di revoca.

FastAPI supporta questi pattern tramite utility come fastapi.security e li documenta chiaramente in OpenAPI.

Nozioni base per le password

Se memorizzi password utente, mai salvare in testo semplice. Conserva un hash salato e lento (es. bcrypt/argon2 tramite una libreria consolidata). Considera anche rate limiting e politiche di lockout degli account.

Una nota di attenzione

La sicurezza dipende dai dettagli: storage dei token, impostazioni CORS, HTTPS, gestione dei segreti e controlli di autorizzazione corretti su ogni endpoint sensibile. Usa i helper integrati come punto di partenza e verifica l'approccio con revisioni e test prima di affidarti a una soluzione in produzione.

Testare app FastAPI

I test sono dove la promessa “funziona sulla mia macchina” diventa fiducia per la produzione. La buona notizia: FastAPI è costruito su Starlette, quindi ottieni ottimi strumenti di test senza molte configurazioni.

Unit test vs integration test

Unit test si concentrano su pezzi piccoli: una funzione che calcola un valore, una dependency che carica l'utente corrente, o un metodo di servizio che parla con il DB (spesso mockato).

Integration test esercitano l'API end-to-end: chiami un endpoint e asserti sulla risposta HTTP completa. Questi test individuano errori di routing, wiring delle dependency e problemi di validazione.

Una suite sana ha più unit test (veloci) e meno integration test (maggiore fiducia).

L'idea del TestClient

Le app FastAPI possono essere testate “come un client” usando il TestClient di Starlette, che invia richieste all'app in-process—nessun server necessario.

from fastapi.testclient import TestClient
from app.main import app

client = TestClient(app)

def test_healthcheck():
    r = client.get("/health")
    assert r.status_code == 200

Cosa testare (checklist pratica)

Testa le cose su cui utenti e altri sistemi contano:

• Status code (200 vs 201 vs 404 vs 422)
• Errori di validazione (campi mancanti, tipi sbagliati, campi extra)
• Forma della risposta (chiavi presenti, tipi corretti, liste vuote)
• Casi limite (zero risultati, input grandi, date al limite)
• Casi auth (nessun token, token scaduto, ruolo insufficiente)

Mantieni i test veloci e ripetibili

Usa dati prevedibili, isola servizi esterni (mock o DB di test) ed evita stato condiviso tra test. I test veloci vengono eseguiti; quelli lenti vengono saltati.

Deploy di FastAPI: opzioni pratiche e checklist

Mettere online un'app FastAPI riguarda soprattutto scegliere il “runner” giusto e aggiungere alcune cose essenziali per la produzione.

Server di sviluppo vs produzione

Quando esegui uvicorn main:app --reload localmente, stai usando una configurazione di sviluppo: reload automatico, errori verbosi e impostazioni comode.

In produzione normalmente esegui Uvicorn senza reload, spesso dietro a un process manager (es. Gunicorn con worker Uvicorn) o dietro un reverse proxy. L'obiettivo è stabilità: riavvii controllati, performance prevedibili e default più sicuri.

Configurazione con variabili d'ambiente

Un pattern comune è:

• Conservare segreti e valori specifici dell'ambiente (URL DB, API key, origini permesse) in variabili d'ambiente.
• Mantenere valori di default sensati per l'uso locale.
• Caricare e validare le impostazioni all'avvio (spesso via Pydantic settings).

Questo permette di distribuire lo stesso codice in più ambienti senza modificare file.

Target di deploy comuni (panoramica rapida)

• Container (Docker/Kubernetes): popolari per build ripetibili e scalabilità.
• Macchine virtuali: semplici e flessibili; utili se gestisci i tuoi server.
• Serverless: funziona per API più piccole; attenzione ai cold start e ai limiti della piattaforma.

Checklist pratica per il deploy

Prima di dichiarare “fatto”, assicurati di avere:

• Logging: log strutturati, request ID (se serve) e livelli di log per ambiente.
• Health checks: endpoint come /health per monitoraggio e bilanciatori.
• Gestione degli errori: risposte JSON coerenti; non esporre stack trace agli utenti.
• Timeout e limiti: dimensione massima del body, timeout dei worker e rate limiting quando necessario.
• Policy per le docs: decidi se esporre Swagger UI/ReDoc pubblicamente o distribuirle.

Se passi da “funziona in locale” a “pronto per la produzione”, aiuta standardizzare come generi e gestisci il contratto API. Alcuni team affiancano l'output OpenAPI di FastAPI a workflow automatizzati—ad esempio generare client, validare richieste in CI e distribuire con processi coerenti. Strumenti come Koder.ai possono inserirsi qui: puoi descrivere l'API che vuoi in chat, iterare sugli endpoint e i modelli rapidamente, e poi esportare il codice sorgente per una normale revisione/deploy.

Quando usare FastAPI (e quando no)

FastAPI è una scelta solida quando vuoi un modo moderno e pulito per costruire API REST in Python—soprattutto se tieni alla chiarezza di request/response e al comportamento prevedibile mentre l'API cresce.

Casi d'uso ideali

FastAPI tende a brillare in queste situazioni:

• Servizi interni dove i team vogliono iterare rapidamente, avere endpoint leggibili e contratti condivisi tra servizi.
• API pubbliche che beneficiano di validazione rigorosa e gestione coerente degli errori.
• Microservizi dove piccole API focalizzate vengono deployate indipendentemente.
• Prototipi e MVP dove vuoi muoverti velocemente senza rinunciare a struttura (validazione + docs).

Quando scegliere un altro strumento

FastAPI non è sempre la risposta più semplice:

• Se stai scrivendo uno script one-off o un piccolo webhook, qualcosa di più leggero (o anche Python puro) può bastare.
• Se il tuo progetto ha bisogno dello stack completo “batteries included” di Django (convenzioni ORM, admin, templating, ecosistema maturo), Django o Django REST Framework possono ridurre scelte e glue code.

Una parola realistica sulle performance

FastAPI può essere molto veloce nella pratica, ma la velocità dipende da chiamate al DB, latenza di rete e logica di business. Aspettati buon throughput e latenze adeguate per carichi API tipici—ma non contare sul framework per risolvere I/O lento o query inefficienti.

Passi successivi

Se FastAPI ti sembra adatto, concentrati su pattern di routing, modelli Pydantic, integrazione col database, task in background e autenticazione di base.

Un percorso pratico è costruire un piccolo set di endpoint, poi espandere con dependency riutilizzabili e test man mano che l'API cresce. Se vuoi accelerare la scaffolding iniziale (route, modelli e struttura pronta per il deploy), considera un workflow di prototipazione—ad esempio mappare gli endpoint in una “planning mode” e iterare da una singola specifica. È un'area dove Koder.ai può essere utile: puoi prototipare un'app guidata da API via chat, affinare il codice generato ed esportarlo quando sei pronto a eseguirlo come un normale progetto.