# API REST con FastAPI en Windows

Guía de Bitflow Solutions. Versión web: https://bitflow-solutions.com/guias-tecnicas/api-rest-con-fastapi/

## ¿Qué vas a aprender?

- Preparar Python en Windows y un entorno virtual para el proyecto.
- Crear una API REST con FastAPI y modelos de datos validados con Pydantic.
- Usar la documentación interactiva que FastAPI genera sola (`/docs`).
- Probar la API desde PowerShell y con pruebas automáticas (pytest).
- Empaquetarla en un contenedor Docker listo para desplegar.

## Requisitos previos

- **Windows 10 u 11** con **PowerShell** (viene instalado: búscalo en el menú Inicio).
- **Python 3.10 o superior** (en el paso 1 se instala si no lo tienes).
- **Visual Studio Code** con la extensión *Python* de Microsoft, o el editor que prefieras.
- Nociones básicas de Python y de qué es una API REST (GET, POST, JSON).
- **Docker Desktop** con WSL 2, solo para el último paso (opcional).

## Paso a paso

### 1. Instalar Python

```powershell
winget install -e --id Python.Python.3.12
python --version
pip --version
```

### 2. Proyecto y entorno virtual

```powershell
mkdir C:\proyectos\api-tareas
cd C:\proyectos\api-tareas
python -m venv .venv
.venv\Scripts\Activate.ps1
```

### 3. Instalar FastAPI

```powershell
pip install "fastapi[standard]"
pip freeze | Out-File -Encoding utf8 requirements.txt
```

### 4. Primera API (main.py)

```python
from fastapi import FastAPI

app = FastAPI(title="API de tareas")


@app.get("/")
def inicio():
    return {"mensaje": "Hola desde FastAPI"}
```

### 5. Servidor de desarrollo

```powershell
fastapi dev main.py
```

- API: http://127.0.0.1:8000
- Documentación: http://127.0.0.1:8000/docs
- Parar: Ctrl + C

### 6. Modelo y endpoints de tareas (main.py)

```python
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel

app = FastAPI(title="API de tareas")


class TareaNueva(BaseModel):
    titulo: str
    hecha: bool = False


class Tarea(TareaNueva):
    id: int


tareas: list[Tarea] = []


@app.get("/")
def inicio():
    return {"mensaje": "Hola desde FastAPI"}


@app.get("/tareas")
def listar_tareas() -> list[Tarea]:
    return tareas


@app.post("/tareas", status_code=201)
def crear_tarea(nueva: TareaNueva) -> Tarea:
    tarea = Tarea(id=len(tareas) + 1, **nueva.model_dump())
    tareas.append(tarea)
    return tarea


@app.get("/tareas/{tarea_id}")
def leer_tarea(tarea_id: int) -> Tarea:
    for tarea in tareas:
        if tarea.id == tarea_id:
            return tarea
    raise HTTPException(status_code=404, detail="Tarea no encontrada")
```

### 7. Probar desde PowerShell

```powershell
Invoke-RestMethod -Method Post -Uri http://127.0.0.1:8000/tareas -ContentType "application/json" -Body '{"titulo": "Primera tarea"}'

Invoke-RestMethod http://127.0.0.1:8000/tareas
Invoke-RestMethod http://127.0.0.1:8000/tareas/1
```

### 8. Pruebas automáticas (test_main.py)

```python
from fastapi.testclient import TestClient

from main import app

cliente = TestClient(app)


def test_crear_y_leer_tarea():
    respuesta = cliente.post("/tareas", json={"titulo": "Primera tarea"})
    assert respuesta.status_code == 201
    tarea = respuesta.json()

    respuesta = cliente.get(f"/tareas/{tarea['id']}")
    assert respuesta.status_code == 200
    assert respuesta.json()["titulo"] == "Primera tarea"


def test_tarea_que_no_existe():
    assert cliente.get("/tareas/999").status_code == 404
```

```powershell
pip install pytest
pytest
```

### 9. Contenedor (opcional)

Dockerfile (sin extensión):

```dockerfile
FROM python:3.12-slim

WORKDIR /code
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY main.py .

CMD ["fastapi", "run", "main.py", "--port", "80"]
```

```powershell
docker build -t api-tareas .
docker run -p 8000:80 api-tareas
```

## Errores habituales

- **«python» abre la Microsoft Store**: Windows trae unos alias que mandan a la Store. Desactívalos en *Configuración → Aplicaciones → Configuración avanzada de aplicaciones → Alias de ejecución de aplicaciones* (python.exe y python3.exe) y vuelve a abrir PowerShell.
- **«La ejecución de scripts está deshabilitada en este sistema»**: Sale al activar el entorno virtual. Permite los scripts locales solo para tu usuario y vuelve a ejecutar `.venv\Scripts\Activate.ps1`: `Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser`
- **«fastapi» no se reconoce como comando**: El entorno virtual no está activado (la línea no empieza por `(.venv)`) o FastAPI se instaló fuera de él. Actívalo y repite el paso 3.
- **El puerto 8000 ya está en uso**: Otra aplicación lo ocupa. Arranca en otro puerto y usa esa dirección: `fastapi dev main.py --port 8001`
- **«curl» no funciona como en los ejemplos de Internet**: En Windows PowerShell, `curl` es un alias de `Invoke-WebRequest` y no entiende las opciones de curl. Usa `Invoke-RestMethod` como en el paso 7, o `curl.exe` si quieres el curl real.
- **La API responde 422 Unprocessable Entity**: El cuerpo de la petición no cumple el modelo: falta `titulo`, tiene otro tipo o el JSON no es válido. La respuesta indica qué campo falla; compruébalo en `/docs`.
- **Docker no lee requirements.txt**: Si lo creaste con `>` en Windows PowerShell, el archivo queda en UTF-16. Vuelve a generarlo con `Out-File -Encoding utf8` como en el paso 3.

## Siguientes pasos

- Guardar las tareas en una base de datos, por ejemplo PostgreSQL con SQLModel.
- Proteger los endpoints con OAuth 2.0 y tokens JWT (ver la guía del contrato OpenAPI 3 con OAuth y API Key).
- Publicarla detrás de un API Gateway con cuotas y contratos versionados.
- Automatizar las pruebas y el despliegue con un pipeline de CI/CD.
