En esta guía creamos desde cero, en Windows, una API REST con FastAPI, el framework de Python para APIs: un servicio de tareas con endpoints para listar, crear y consultar, documentación automática, pruebas y un contenedor listo para desplegar. Todos los comandos se escriben en PowerShell, y tienes los mismos pasos en el README.md de la izquierda.
¿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. Instala Python y compruébalo
Abre PowerShell e instala Python con winget, el gestor de paquetes de Windows:
winget install -e --id Python.Python.3.12
También puedes descargarlo de python.org; en ese caso, marca «Add python.exe to PATH» en la primera pantalla del instalador. Cierra y vuelve a abrir PowerShell y comprueba que responde:
python --version
pip --version
2. Crea el proyecto y su entorno virtual
El entorno virtual aísla las dependencias de este proyecto de las del resto del equipo. Al activarlo, la línea de PowerShell empieza por (.venv).
mkdir C:\proyectos\api-tareas
cd C:\proyectos\api-tareas
python -m venv .venv
.venv\Scripts\Activate.ps1
3. Instala FastAPI
El paquete fastapi[standard] incluye el servidor (Uvicorn), la herramienta de línea de comandos fastapi y lo necesario para las pruebas. Guarda las dependencias en requirements.txt, en UTF-8 para que también lo lea Docker:
pip install "fastapi[standard]"
pip freeze | Out-File -Encoding utf8 requirements.txt
4. Escribe tu primera API
Abre la carpeta en Visual Studio Code y, si pregunta qué intérprete de Python usar, elige el de .venv:
code .
Crea el archivo main.py:
from fastapi import FastAPI
app = FastAPI(title="API de tareas")
@app.get("/")
def inicio():
return {"mensaje": "Hola desde FastAPI"}
5. Arranca el servidor de desarrollo
En PowerShell, con el entorno virtual activado:
fastapi dev main.py
Abre http://127.0.0.1:8000 y verás el mensaje en JSON. En http://127.0.0.1:8000/docs tienes la documentación interactiva (Swagger UI), generada a partir del código, desde la que puedes probar cada endpoint. El servidor se recarga solo al guardar; para pararlo, Ctrl + C.
6. Añade un modelo y los endpoints de tareas
Con Pydantic defines la forma de los datos: FastAPI valida cada petición, devuelve un error 422 si no encaja y documenta el contrato en /docs. Sustituye main.py por:
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")
Las tareas se guardan en memoria para mantener el ejemplo simple: se pierden al reiniciar. En un proyecto real irían a una base de datos.
7. Prueba la API desde PowerShell
Abre una segunda ventana de PowerShell (la primera sigue con el servidor) y usa Invoke-RestMethod:
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. Añade pruebas automáticas
Crea test_main.py junto a main.py:
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
Instala pytest y ejecuta las pruebas con el entorno virtual activado:
pip install pytest
pytest
9. Empaquétala en un contenedor (opcional)
Con Docker Desktop abierto, crea un archivo Dockerfile, sin extensión, en la carpeta del proyecto:
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"]
Construye la imagen y arráncala:
docker build -t api-tareas .
docker run -p 8000:80 api-tareas
La API queda en http://127.0.0.1:8000, lista para desplegar en Kubernetes, Azure Container Apps o cualquier plataforma de contenedores.
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.