Instalación y estructura básica de una aplicación FastAPI

FastAPI es un framework moderno para crear APIs web en Python con un rendimiento comparable a Node.js y Go. Destaca por su facilidad de uso, velocidad y validación automática de datos, lo que lo convierte en una excelente opción para desarrolladores que buscan construir APIs robustas rápidamente.

Requisitos previos

Antes de comenzar, asegúrate de tener instalado Python 3.7+ en tu sistema. Para este curso utilizaremos Python 3.13, que ofrece mejoras significativas en rendimiento y nuevas características del lenguaje.

Instalación de FastAPI

Para instalar FastAPI, utilizaremos pip, el gestor de paquetes de Python. Abre una terminal y ejecuta:

pip install fastapi

FastAPI por sí solo no incluye un servidor web, por lo que necesitamos instalar Uvicorn, un servidor ASGI (Asynchronous Server Gateway Interface) de alto rendimiento:

pip install "uvicorn[standard]"

Para un entorno de desarrollo completo, es recomendable instalar todas las dependencias opcionales:

pip install fastapi[all]

Este comando instalará FastAPI junto con Uvicorn, Pydantic (para validación de datos) y otras bibliotecas útiles.

Creación de un entorno virtual

Es una buena práctica trabajar con entornos virtuales para aislar las dependencias de cada proyecto:

# Crear un entorno virtual
python -m venv venv

# Activar el entorno virtual
# En Windows:
venv\Scripts\activate
# En macOS/Linux:
source venv/bin/activate

Una vez activado el entorno virtual, instala las dependencias mencionadas anteriormente.

Tu primera aplicación FastAPI

Vamos a crear una aplicación mínima para verificar que todo funciona correctamente. Crea un archivo llamado main.py con el siguiente contenido:

from fastapi import FastAPI

# Crear una instancia de la aplicación
app = FastAPI()

# Definir una ruta
@app.get("/")
async def root():
    return {"message": "¡Hola, FastAPI!"}

Este código crea una aplicación FastAPI y define una ruta raíz (/) que responde a peticiones GET con un mensaje JSON.

Ejecutando la aplicación

Para ejecutar la aplicación, utiliza Uvicorn desde la línea de comandos:

uvicorn main:app --reload

Donde:

• main es el nombre del archivo Python (sin la extensión .py)
• app es el nombre de la instancia de FastAPI en ese archivo
• --reload activa el modo de recarga automática (útil durante el desarrollo)

Ahora puedes abrir tu navegador en http://127.0.0.1:8000 y verás el mensaje JSON:

{"message": "¡Hola, FastAPI!"}

Documentación automática

Una de las características más potentes de FastAPI es la generación automática de documentación interactiva. Accede a:

• http://127.0.0.1:8000/docs para la documentación con Swagger UI
• http://127.0.0.1:8000/redoc para una documentación alternativa con ReDoc

Estas interfaces te permiten explorar y probar tu API directamente desde el navegador.

Estructura básica de un proyecto FastAPI

Para proyectos reales, es recomendable seguir una estructura organizada. Aquí tienes una estructura básica:

mi_proyecto/
│
├── app/                    # Directorio principal de la aplicación
│   ├── __init__.py         # Hace que "app" sea un paquete Python
│   ├── main.py             # Punto de entrada de la aplicación
│   ├── models/             # Modelos Pydantic para validación de datos
│   │   └── __init__.py
│   ├── routers/            # Rutas organizadas por módulos
│   │   └── __init__.py
│   └── core/               # Configuraciones centrales
│       └── __init__.py
│
├── tests/                  # Pruebas unitarias e integración
│   └── __init__.py
│
├── .env                    # Variables de entorno (no incluir en control de versiones)
├── .gitignore              # Archivos a ignorar en Git
├── requirements.txt        # Dependencias del proyecto
└── README.md               # Documentación del proyecto

Vamos a implementar una versión básica de esta estructura:

1. Crea la estructura de directorios:

mkdir -p app/models app/routers app/core tests
touch app/__init__.py app/models/__init__.py app/routers/__init__.py app/core/__init__.py tests/__init__.py

2. Crea el archivo app/main.py:

from fastapi import FastAPI
from app.routers import items, users

app = FastAPI(
    title="Mi API",
    description="Una API de ejemplo con FastAPI",
    version="0.1.0"
)

# Incluir routers
app.include_router(items.router)
app.include_router(users.router)

@app.get("/")
async def root():
    return {"message": "Bienvenido a mi API"}

3. Crea el archivo app/routers/users.py:

from fastapi import APIRouter

router = APIRouter(
    prefix="/users",
    tags=["users"],
    responses={404: {"description": "No encontrado"}},
)

@router.get("/")
async def read_users():
    return [{"username": "Rick"}, {"username": "Morty"}]

@router.get("/{username}")
async def read_user(username: str):
    return {"username": username}

4. Crea el archivo app/routers/items.py:

from fastapi import APIRouter

router = APIRouter(
    prefix="/items",
    tags=["items"],
    responses={404: {"description": "No encontrado"}},
)

@router.get("/")
async def read_items():
    return [{"name": "Item 1"}, {"name": "Item 2"}]

@router.get("/{item_id}")
async def read_item(item_id: int):
    return {"item_id": item_id, "name": f"Item {item_id}"}

5. Crea un archivo requirements.txt en la raíz del proyecto:

fastapi>=0.110.0
uvicorn[standard]>=0.27.0

Ejecutando la aplicación estructurada

Para ejecutar esta aplicación estructurada, usa:

uvicorn app.main:app --reload

Ahora puedes acceder a:

• http://127.0.0.1:8000/ - Mensaje de bienvenida
• http://127.0.0.1:8000/users/ - Lista de usuarios
• http://127.0.0.1:8000/items/ - Lista de items
• http://127.0.0.1:8000/docs - Documentación interactiva

Configuración de la aplicación

FastAPI permite personalizar varios aspectos de la aplicación al inicializarla:

app = FastAPI(
    title="Mi API",
    description="Una API de ejemplo con FastAPI",
    version="0.1.0",
    openapi_url="/api/v1/openapi.json",
    docs_url="/documentacion",
    redoc_url="/redoc",
    openapi_tags=[
        {
            "name": "users",
            "description": "Operaciones con usuarios",
        },
        {
            "name": "items",
            "description": "Gestión de items",
        },
    ],
)

Estos parámetros permiten:

• Personalizar el título, descripción y versión de la API
• Cambiar las URLs de la documentación y el esquema OpenAPI
• Añadir descripciones a las etiquetas utilizadas en los routers

Archivos estáticos y plantillas

FastAPI puede servir archivos estáticos y renderizar plantillas HTML. Para archivos estáticos:

from fastapi import FastAPI
from fastapi.staticfiles import StaticFiles

app = FastAPI()

# Montar archivos estáticos
app.mount("/static", StaticFiles(directory="static"), name="static")

Para usar plantillas, necesitas instalar Jinja2:

pip install jinja2

Y configurar el motor de plantillas:

from fastapi import FastAPI, Request
from fastapi.templating import Jinja2Templates
from fastapi.staticfiles import StaticFiles

app = FastAPI()
app.mount("/static", StaticFiles(directory="static"), name="static")
templates = Jinja2Templates(directory="templates")

@app.get("/pagina/{id}")
async def read_item(request: Request, id: str):
    return templates.TemplateResponse(
        "item.html", {"request": request, "id": id}
    )

Esta estructura básica te proporciona un punto de partida sólido para desarrollar aplicaciones más complejas con FastAPI, manteniendo el código organizado y fácil de mantener.