Todas las guías
  1. Inicio
  2. Guías técnicas
  3. APIs

APIsNivel básico

Cómo crear una API REST con FastAPI en Windows: requisitos, comandos y primer despliegue

5 min de lectura

Todas las guías

Cómo crear una API REST con FastAPI en Windows: requisitos, comandos y primer despliegue

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.

Compartir

Más guías sobre

Ver todas las guías

Otras guías técnicas

Ver todas las guías

APIsIntermedio

Estructura básica de una API en IBM API Connect 10

Cómo se estructura una API en IBM API Connect 10: contrato OpenAPI con x-ibm-configuration, Client ID y Client Secret, producto con planes y límites, y validación y publicación con el CLI apic.

Leer la guía 7 min de lectura

IntegraciónIntermedio

Comandos básicos de administración de TIBCO ActiveSpaces 5.2

Los comandos del día a día en TIBCO ActiveSpaces 5.2: servicio de realm sobre servidores FTL, tibdg, definición del grid, tablas, arranque de procesos, estado, escalado con copysets, checkpoints y logs.

Leer la guía 8 min de lectura

DevOpsBásico

Estructura básica de un CI/CD con GitHub Actions

Un pipeline completo con GitHub Actions: pruebas en cada push y pull request, imagen Docker en GitHub Container Registry y despliegue a un entorno protegido, con un workflow listo para copiar.

Leer la guía 6 min de lectura

DesarrolloBásico

Buenas prácticas de desarrollo en Java con Spring Boot

Las prácticas que más se notan en un servicio Spring Boot: estructura, inyección por constructor, DTOs, validación, errores, configuración, transacciones, logs, comentarios, pruebas y calidad automatizada.

Leer la guía 8 min de lectura

Contacto

Construye hoy tu próxima ventaja competitiva

Hablemos sobre cómo podemos ayudarte. Te respondemos con una propuesta técnica clara, sin compromiso.

Solicita información

Los campos marcados con son obligatorios.