FastAPI.txt

=====================
Guía de FastAPI by dM
=====================

FastAPI es un framework web moderno, rápido (de alto rendimiento) y fácil de
usar para construir APIs en Python, basado en estándares abiertos como OpenAPI
y JSON Schema.

Según la web oficial las características principales son:

-Rápido: Rendimiento muy alto, comparable a NodeJS y Go (gracias a Starlette y
Pydantic). Uno de los frameworks de Python más rápidos disponibles .

-Rápido para codificar: aumenta la velocidad para desarrollar funciones entre un
200% y un 300%.*

-Menos errores: reduce aproximadamente el 40% de los errores inducidos por
humanos (desarrolladores). *

-Intuitivo: Excelente compatibilidad con el editor. Finalización en todas
partes. Menos tiempo de depuración.

-Fácil: Diseñado para ser fácil de usar y aprender. Menos tiempo leyendo
documentos.

-En resumen: Minimiza la duplicación de código. Múltiples funciones en cada
declaración de parámetro. Menos errores.

-Robusto: Obtenga código listo para producción. Con documentación interactiva
automática.

-Basado en estándares: basado en (y totalmente compatible con) los estándares
abiertos para API: OpenAPI (anteriormente conocido como Swagger) y JSON Schema .

Características principales
===========================

Alto rendimiento:

-Basado en Starlette (para manejo asíncrono) y Pydantic (para validación de
datos).

-Comparable en velocidad a Node.js y Go gracias a su soporte nativo para
async/await.

Generación automática de documentación:

-Crea documentación interactiva (Swagger UI y ReDoc) automáticamente gracias a
OpenAPI.

Soporte para ASGI:

-Compatible con el estándar ASGI (Asynchronous Server Gateway Interface), ideal
para conexiones asíncronas (WebSockets, HTTP/2).

Fácil de aprender:

-Diseño intuitivo similar a Flask, pero con capacidades más avanzadas.

¿Cuándo usar FastAPI?
=====================

Para construir APIs RESTful rápidas y escalables.

Cuando necesitas documentación automática.

Si trabajas con microservicios o aplicaciones con alta concurrencia.

Para integrar sistemas con GraphQL (mediante librerías como strawberry).

Limitaciones:

-No es un framework full-stack (como Django): está enfocado en APIs.

-Menor cantidad de librerías de terceros comparado con Flask o Django (aunque
está creciendo rápidamente).

FastAPI es ideal si buscas rendimiento, simplicidad y modernidad en el
desarrollo de APIs con Python.

Fuente
======

Deepseek

=====================
Hola mundo en FastAPI
=====================

1- Instalar el gestor de paquetes pip

$ sudo apt install pip

2- Instalación de fastapi

$ pip install "fastapi[standard]"

El comando anterior nos va a dar error, pero tiene una explicación, el clásico
error de externally-managed-environment! no te preocupes, esto pasa porque las
versiones modernas de Debian (y otras distros como Ubuntu) protegen el Python
del sistema para que no lo rompas instalando librerías sueltas.

La solución correcta y profesional es usar un entorno virtual. Es como crear
una "burbuja" aislada para tu proyecto de FastAPI.

3- Crear un entorno virtual con Python 3

Instalar python3-venv

$ sudo apt install python3-venv

Crear el entorno virtual:

$ python3 -m venv fastapienv

Activar el entorno:

$ source fastapienv/bin/activate

4- Instalación de fastapi dentro del entorno virtual

(fastapienv) $ pip install "fastapi[standard]"

Este comando colectara y descargara una serie de paquetes de python para que el
fastapi quede funcional.

5- Comprobar la instalación y la versión

(fastapienv) $ pip show fastapi
Name: fastapi
Version: 0.128.1

También podemos usar el comando pip listpara ver una lista rápida de todos los
paquetes instalados en el entorno y sus versiones:

(fastapienv) $ pip list

También podemos hacer una comprobación rápida con Python

Si quieres estar 100% seguro de que Python puede "ver" la librería, puedes
ejecutar este comando rápido que imprime la versión directamente:

(fastapienv) $ python -c "import fastapi; print(fastapi.__version__)"

0.128.1

6- Ahora vamos a escribir un script básico de python para hacer un hola mundo:

Crea un archivo llamado main.py y pega el siguiente código:

from fastapi import FastAPI

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

# Definimos una ruta (endpoint)
@app.get("/")
def read_root():
    return {"Hola": "Mundo"}

Ejecuta el servidor

Vuelve a la terminal y arranca tu aplicación con este comando:

$ fastapi dev main.py

¡Prueba tu API!

Una vez que el servidor esté corriendo, puedes ver los resultados en dos lugares:

El resultado: Abre tu navegador en http://127.0.0.1:8000. Verás el JSON:
{"Hola": "Mundo"}.

La documentación interactiva: Ve a http://127.0.0.1:8000/docs. FastAPI crea
automáticamente una interfaz de Swagger UI donde puedes probar tus rutas
directamente.

--- ¿Qué pasó aquí? ---

app = FastAPI(): Es el corazón de tu aplicación.

@app.get("/"): Es un "decorador" que le dice a FastAPI que la función de abajo
se encargará de las peticiones que lleguen a la raíz (/) usando el método GET.

El retorno: FastAPI convierte automáticamente los diccionarios de Python a
formato JSON, que es el estándar de la web.

Ejemplo con parámetros en la URL:

Los parámetros de URL son la forma en que haces que tu API sea dinámica. En
FastAPI, esto es muy intuitivo porque usas la misma sintaxis que los "f-strings"
de Python.

Existen dos formas principales de recibir datos en una URL: Path Parameters
(dentro de la ruta) y Query Parameters (después del signo ?).

1. Path Parameters (Parámetros de ruta)

Se usan cuando el dato es parte esencial de la dirección. Por ejemplo:
127.0.0.1/saludo/Pepe.

Modifica tu archivo main.py así:

from fastapi import FastAPI

app = FastAPI()

@app.get("/saludo/{nombre}")
def say_hello(nombre: str):
    return {"mensaje": f"Hola {nombre}, bienvenido a FastAPI"}

Explicación:

{nombre}: Define una variable en la ruta.

nombre: str: FastAPI valida automáticamente que sea una cadena de texto. Si
esperas un número, podrías poner int.

Probar: Escribe en la url http://127.0.0.1:8000/saludo/Pepe

El api retorna el json {"mensaje":"Hola pepe, bienvenido a FastAPI"}

2. Query Parameters (Parámetros de consulta)

Se usan para valores opcionales, filtros o búsquedas. Por ejemplo:
127.0.0.1/saludo?nombre=Pepe&edad=30.

from fastapi import FastAPI

app = FastAPI()

@app.get("/personalizado/")
def saludo_completo(nombre: str, edad: int):
    return {
        "usuario": nombre,
        "edad_proxima": edad + 1,
        "nota": "Fíjate cómo FastAPI sumó 1 porque definimos edad como int"
    }

¡Pruébalo ahora mismo!

Asegúrate de que tu servidor esté corriendo (fastapi dev main.py).

Ve a tu navegador y entra en: http://127.0.0.1:8000/personalizado/?nombre=Pepe&edad=25

El api retorna el json {"usuario":"Pepe","edad_proxima":26,"nota":"Fíjate cómo
FastAPI sumó 1 porque definimos edad como int"}

La magia de la validación:

Si intentas entrar a /personalizado/?nombre=Pepe&edad=Diez, FastAPI te
devolverá un error 422 Unprocessable Entity avisándote que edad debe ser un
número entero. ¡Te ahorra mucho trabajo de validación manual!

Devuelve el json:

{"detail":[{"type":"int_parsing","loc":["query","edad"],"msg":"Input should be a
valid integer, unable to parse string as an integer","input":"Diez"}]}

Fuentes
=======

Gemini IA

Web oficial: https://fastapi.tiangolo.com/

=================
¿Qué es Pydantic?
=================

Si FastAPI es el motor de tu API, Pydantic es el guardaespaldas que revisa quién
entra y qué trae puesto.

En términos técnicos, Pydantic es una librería de Python para la validación de
datos y la gestión de configuraciones basada en "type hints" (pistas de tipo)
de Python.

1. Validación en tiempo real

Cuando defines una clase con Pydantic, no solo estás creando una estructura,
estás creando un filtro. Si dices que un campo es un int y llega un "hola",
Pydantic lanza un error antes de que ese dato llegue a tu lógica de negocio.

2. Conversión de tipos (Coerción)

Pydantic es inteligente. Si defines un campo como float y el usuario envía la
cadena "10.5", Pydantic lo convertirá automáticamente al número 10.5. Esto evita
que tengas que hacer float(valor) manualmente en todo tu código.

3. Ejemplo comparativo

Mira la diferencia entre validar a mano y usar Pydantic:

Sin Pydantic (Validación manual):
def procesar_usuario(data):
    if "id" not in data or not isinstance(data["id"], int):
        raise ValueError("ID inválido")
    if "email" not in data or "@" not in data["email"]:
        raise ValueError("Email inválido")
    # ... y así con cada campo

Con Pydantic:

from pydantic import BaseModel, EmailStr

class Usuario(BaseModel):
    id: int
    email: EmailStr  # Valida automáticamente que sea un email real
    nombre: str

# Solo con esto, Pydantic ya sabe qué hacer

¿Por qué FastAPI y Pydantic son "mejores amigos"?

FastAPI fue construido específicamente sobre Pydantic. Cuando usas ambos:

-Documentación automática: Los modelos de Pydantic generan el esquema JSON que
ves en Swagger (/docs).

-Seguridad: Garantizas que tu base de datos nunca reciba basura.

-Velocidad de desarrollo: Escribes menos código porque la validación ocurre
"tras bambalinas".

Dato curioso: Pydantic es extremadamente rápido porque su núcleo está escrito en
Rust, lo que lo hace una de las librerías de validación más potentes en el
ecosistema Python.

Ejemplo:

Para que veas a Pydantic en acción, vamos a crear un script donde definimos un
modelo para un "Ítem de Inventario". Aquí obligaremos a que la cantidad sea un
número entero.

Copia este código en tu archivo:

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

# Definimos el modelo con Pydantic
class Item(BaseModel):
    nombre: str
    cantidad: int  # Este es el dato que vamos a poner a prueba

@app.post("/items/")
def crear_item(item: Item):
    return {"mensaje": "Validación exitosa", "data": item}

¿Qué pasa si envías un string donde se espera un int?

Aquí es donde FastAPI y Pydantic brillan. No necesitas escribir
if type(cantidad) != int. Si intentas enviar un texto, ocurrirá lo siguiente:

1. La Petición (Cuerpo del JSON)

Imagina que envías esto a través de la documentación (/docs) o una herramienta
como Postman:

{
  "nombre": "Teclado",
  "cantidad": "muchos" 
}

2. La Respuesta de FastAPI

FastAPI detendrá la ejecución antes de entrar a tu función y te devolverá un
Error 422 (Unprocessable Entity) con un detalle exacto de qué salió mal:

{
  "detail": [
    {
      "type": "int_parsing",
      "loc": ["body", "cantidad"],
      "msg": "Input should be a valid integer, unable to parse string as an integer",
      "input": "muchos"
    }
  ]
}

El "Superpoder" de la Coerción de Datos

Hay un detalle curioso: si envías el número como texto, por ejemplo "10",
Pydantic no dará error.

Pydantic intentará convertirlo (coerción):

"10" (string) -> lo convierte a 10 (int). Pasa la validación.

"diez" (string) -> no puede convertirlo. Lanza error.

Pruébalo tú mismo:

Ejecuta el servidor: fastapi dev main.py.

Ve a http://127.0.0.1:8000/docs.

Abre el método POST, dale a Try it out.

En el campo cantidad, escribe una palabra y dale a Execute. Verás el error
estructurado que te puse arriba.

Un ejemplo más avanzado
=======================

Algo muy común y avanzado para empezar es el manejo de modelos de datos. En una
API real, no solo envías texto, sino que recibes objetos complejos (como un
usuario o un producto) y quieres que FastAPI valide que todo esté correcto antes
de procesarlo.

Para esto usamos Pydantic. Vamos a crear un ejemplo de un mini-inventario donde
puedes "crear" un producto y FastAPI validará el precio, el nombre y los
impuestos.

Ejemplo: Creación de un Producto (POST)

Modifica tu main.py con este código:

from fastapi import FastAPI
from pydantic import BaseModel
from typing import Optional

app = FastAPI()

# Definimos el esquema del objeto usando Pydantic
class Producto(BaseModel):
    nombre: str
    precio: float
    en_oferta: Optional[bool] = None
    categoria: str = "General"

# Simulamos una "base de datos" simple
db_productos = {}

@app.post("/productos/{producto_id}")
def crear_producto(producto_id: int, producto: Producto):
    # Aquí FastAPI ya validó que 'producto' tiene la estructura correcta
    db_productos[producto_id] = producto.dict()
    
    return {
        "mensaje": "Producto creado con éxito",
        "id": producto_id,
        "data": producto
    }

@app.get("/productos/{producto_id}")
def obtener_producto(producto_id: int):
    return db_productos.get(producto_id, {"error": "Producto no encontrado"})

¿Por qué esto es "nivel pro"?

-Tipado fuerte: Al usar precio: float, si alguien intenta enviar "gratis",
FastAPI responderá automáticamente con un error indicando que se esperaba un
número.

-Método POST: A diferencia de GET (que es para leer), usamos POST para enviar
datos pesados en el "cuerpo" (body) de la petición.

-Valores por defecto: categoria tiene un valor inicial, así que es opcional para
el usuario.

-JSON Automático: No tienes que convertir nada manualmente; FastAPI entiende la
clase de Pydantic y la transforma.

Cómo probarlo?

Como los navegadores solo hacen peticiones GET fácilmente, la mejor forma de
probar este ejemplo es usando la documentación interactiva:

Ve a http://127.0.0.1:8000/docs

Busca el botón azul de POST.

Haz clic en "Try it out".

Modifica el JSON en el cuadro de texto y dale a "Execute".

¡Verás cómo FastAPI te responde con el objeto procesado!

También puedes usar el método GET para listar los productos registrados según su
id.

Fuente
======

Gemini IA

===============================
¿Es fast api rival para Django?
===============================

Más que rivales directos, son herramientas con filosofías distintas. En el mundo
del desarrollo se suele decir que Django es un portaaviones y FastAPI es un jet
supersónico.

Aquí tienes la comparativa real para que sepas cuándo usar cada uno:

1. La filosofía: "Baterías incluidas" vs "Micro-framework"

Django: Viene con todo de fábrica. Sistema de usuarios, panel de administración
(el famoso /admin), manejo de base de datos (ORM), seguridad contra ataques
comunes y formularios. Es ideal si quieres construir una aplicación completa
(red social, e-commerce, CMS) muy rápido.

FastAPI: Es minimalista. Te da las herramientas para crear el endpoint y validar
datos, pero si quieres una base de datos o sistema de usuarios, tú eliges y
conectas la librería que prefieras (como SQLAlchemy o Tortoise).

2. Rendimiento y Velocidad

FastAPI: Es mucho más rápido en ejecución. Está construido sobre estándares
modernos como ASGI y asyncio, lo que le permite manejar miles de peticiones
simultáneas con muy pocos recursos. Es el rey para Microservicios e Inteligencia
Artificial.

Django: Es más pesado y, aunque ya soporta funciones asíncronas, su núcleo sigue
siendo mayoritariamente síncrono. Para la mayoría de las webs normales esto no
importa, pero en aplicaciones de alto tráfico o tiempo real, FastAPI gana.

¿Son rivales?
=============

Sí y no. Son rivales cuando necesitas crear una API REST. Antes, la opción por
defecto era Django con Django Rest Framework (DRF). Hoy en día, mucha gente
prefiere FastAPI para eso porque es más moderno, ligero y rápido de programar.

Sin embargo, si tu proyecto necesita un sistema de gestión de contenidos,
perfiles de usuario complejos y un panel de administración en 5 minutos, Django
sigue siendo el rey indiscutible.

Fuente
======

Gemini IA

==========
Swagger UI
==========

FastAPI integra Swagger UI por defecto, permite a cualquier persona, ya sea su
equipo de desarrollo o sus usuarios finales, visualizar e interactuar con los
recursos de la API sin necesidad de implementar la lógica de implementación.
Se genera automáticamente a partir de la especificación de OpenAPI
(anteriormente conocida como Swagger), y la documentación visual facilita la
implementación en el backend y el uso del cliente.

Swagger permite el diseño, la gobernanza y las pruebas a lo largo de todo el
ciclo de vida de la API habilitada para IA, lo que garantiza la calidad en cada
paso.

Repositorio: https://github.com/swagger-api/swagger-ui

Web del proyecto: https://swagger.io/

=========
Starlette
=========

FastAPI integra Starlette que es un marco/kit de herramientas ASGI (Interfaz de
puerta de enlace de servidor asincrónica) ligero, ideal para crear servicios web
asincrónicos en Python.

Está listo para producción y le ofrece lo siguiente:

-Un marco web HTTP ligero y de baja complejidad.
-Compatibilidad con WebSocket.
-Tareas en segundo plano en proceso.
-Eventos de inicio y apagado.
-Cliente de prueba creado en httpx.
-CORS, GZip, archivos estáticos, respuestas en streaming.
-Soporte de sesión y cookies.
-Pocas dependencias duras.
-Compatible con backends asyncio y trio.
-Excelente rendimiento general en comparación con puntos de referencia
independientes.

Repositorio: https://github.com/Kludex/starlette?tab=readme-ov-file

Web oficial: https://www.starlette.dev/

============================================================
CRUD (Create, Read, Update, Delete) funcional usando FastAPI
============================================================

Para que esto funcione en un solo archivo main.py de forma sencilla,
utilizaremos una lista en memoria como "base de datos".

Código del archivo main.py

from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
from typing import Optional, List

app = FastAPI(title="CRUD de Estudiantes")

# Modelo de datos
class Estudiante(BaseModel):
    id: Optional[int] = None
    nombre: str
    edad: int

# Base de datos ficticia (en memoria)
db_estudiantes = []
id_counter = 1

@app.get("/", tags=["Inicio"])
def read_root():
    return {"mensaje": "Bienvenido a la API de Estudiantes"}

# 1. CREATE: Registrar un estudiante
@app.post("/estudiantes/", response_model=Estudiante, tags=["Estudiantes"])
def crear_estudiante(estudiante: Estudiante):
    global id_counter
    estudiante.id = id_counter
    db_estudiantes.append(estudiante)
    id_counter += 1
    return estudiante

# 2. READ: Obtener todos los estudiantes
@app.get("/estudiantes/", response_model=List[Estudiante], tags=["Estudiantes"])
def obtener_estudiantes():
    return db_estudiantes

# 3. READ: Obtener un estudiante por ID
@app.get("/estudiantes/{estudiante_id}", response_model=Estudiante, tags=["Estudiantes"])
def obtener_estudiante(estudiante_id: int):
    estudiante = next((e for e in db_estudiantes if e.id == estudiante_id), None)
    if not estudiante:
        raise HTTPException(status_code=404, detail="Estudiante no encontrado")
    return estudiante

# 4. UPDATE: Actualizar datos de un estudiante
@app.put("/estudiantes/{estudiante_id}", response_model=Estudiante, tags=["Estudiantes"])
def actualizar_estudiante(estudiante_id: int, estudiante_actualizado: Estudiante):
    for index, e in enumerate(db_estudiantes):
        if e.id == estudiante_id:
            estudiante_actualizado.id = estudiante_id
            db_estudiantes[index] = estudiante_actualizado
            return estudiante_actualizado
    raise HTTPException(status_code=404, detail="Estudiante no encontrado")

# 5. DELETE: Eliminar un estudiante
@app.delete("/estudiantes/{estudiante_id}", tags=["Estudiantes"])
def eliminar_estudiante(estudiante_id: int):
    for index, e in enumerate(db_estudiantes):
        if e.id == estudiante_id:
            del db_estudiantes[index]
            return {"mensaje": f"Estudiante con ID {estudiante_id} eliminado"}
    raise HTTPException(status_code=404, detail="Estudiante no encontrado")

-----

Cómo ejecutarlo y probarlo:

Corre el servidor: Ejecuta el siguiente comando en tu terminal:

$ fastapi dev main.py

Prueba la API (Interfaz Interactiva): FastAPI genera documentación automática.
Abre tu navegador en:

http://127.0.0.1:8000/docs (Swagger UI)

Desde ahí puedes hacer clic en "Try it out" para enviar nombres y edades.

Puntos clave del código:

Pydantic (BaseModel): Lo usamos para definir la estructura del estudiante y que
FastAPI valide que el nombre sea texto y la edad un número automáticamente.

HTTP Status Codes: Si intentas buscar o borrar un ID que no existe, el sistema
devuelve un error 404 real, no solo un mensaje vacío.

Tags: Los añadí para que en la documentación de Swagger todo se vea organizado
por categorías.

Fuente
======

Gemini IA

Cors
====

Para que una app del front como Nuxt pueda leer los datos de tu FastAPI local,
debes habilitar CORS en tu main.py de Python. Si no lo haces, la función
que consultara el API puede fallar por lo tanto main.py debe qiedar así:

from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware

app = FastAPI()

# Configurar CORS
app.add_middleware(
    CORSMiddleware,
    allow_origins=["*"], # En producción cambia esto por la URL de tu Nuxt
    allow_methods=["*"],
    allow_headers=["*"],
)

# Definimos una ruta (endpoint)
@app.get("/")
def read_root():
    return {"Hola": "Mundo"}

Fuente
======

Gemini IA

========================================
Corrre FastAPI en una ip local de la red
========================================

Por defecto, FastAPI (y Uvicorn) se "atan" a 127.0.0.1 (localhost), lo que
significa que solo aceptan conexiones desde tu propia computadora. Para que sea
accesible desde otros dispositivos en tu red local bajo la IP 192.168.12.216
por ejemplo, debes cambiar el host.

Usando el comando CLI (Recomendado)

Para el modo de desarrollo, usa el parámetro --host:

$ fastapi dev main.py --host 0.0.0.0