Cómo crear una API de búsqueda de datos en Python: paso a paso
Este tutorial muestra cómo crear una API de búsqueda de datos en Python para exponer consultas simples, con filtros, paginación y seguridad básica. Tener una API de búsqueda permite poner datos a disposición de dashboards, aplicaciones o automatizaciones sin exponer la base de datos directamente. Es útil cuando se quiere compartir solo un subconjunto de datos (por ejemplo 10-100 campos por registro) y aplicar límites (por ejemplo 10-100 resultados por petición) para evitar sobrecarga. Para cargas ligeras a moderadas (hasta unas pocas centenas de peticiones por minuto) SQLite y FastAPI pueden ser suficientes; para cargas mayores se recomienda migrar a PostgreSQL o a un servicio gestionado.
Pre-requisitos
- Python 3.9+ instalado (compruébelo con
python --version) - Conocimientos básicos de Python y SQL
- Bibliotecas: FastAPI, Uvicorn, SQLAlchemy, pydantic
- Editor de texto y terminal
Recomiendo crear un entorno virtual para aislar dependencias. Un ejemplo rápido:
python -m venv .venv
source .venv/bin/activate # on Windows: .venv\\Scripts\\activate
python -m pip install --upgrade pip
pip install fastapi uvicorn sqlalchemy pydantic
Paso 1: Crear un proyecto mínimo e instalar dependencias
Comenzamos creando un entorno e instalando las bibliotecas. FastAPI sirve para construir la API, Uvicorn es el servidor ASGI recomendado para desarrollo y producción ligera, SQLAlchemy para acceder a la base de datos y pydantic para validar peticiones. Esta separación ayuda a mantener el código testeable y seguro.
En un proyecto pequeño, la estructura mínima puede ser:
./
├── main.py
├── db_setup.py
├── schemas.py
└── data.db # creado por el script de setup
Paso 2: Preparar una base de datos SQLite de ejemplo
Usamos SQLite por simplicidad. SQLite crea un archivo único (por ejemplo data.db) y es adecuado para desarrollo o datos hasta decenas de miles de registros. Para bases con >1M registros o concurrencia elevada, use PostgreSQL. El ejemplo crea una tabla "items" con algunos registros de prueba — suficiente para experimentar filtros y paginación.
# db_setup.py
from sqlalchemy import create_engine, Column, Integer, String, MetaData, Table
def init_db(path='sqlite:///data.db'):
engine = create_engine(path)
metadata = MetaData()
items = Table('items', metadata,
Column('id', Integer, primary_key=True),
Column('name', String),
Column('category', String),
Column('price', Integer))
metadata.create_all(engine)
# insertar datos de ejemplo
with engine.connect() as conn:
conn.execute(items.insert(), [
{'name': 'Camisola', 'category': 'Vestuário', 'price': 30},
{'name': 'Calças', 'category': 'Vestuário', 'price': 45},
{'name': 'Mouse', 'category': 'Eletrónica', 'price': 25},
{'name': 'Teclado', 'category': 'Eletrónica', 'price': 50},
])
if __name__ == '__main__':
init_db()
Ejecute python db_setup.py para crear el archivo data.db con algunos registros.
Paso 3: Definir el modelo de petición y respuesta con pydantic
Usamos pydantic para validar parámetros de búsqueda: q (texto), category (filtro), min_price/max_price y paginación (limit/offset). Validar los parámetros evita peticiones malformadas y limita la carga en el servidor — por ejemplo imponemos limit entre 1 y 100. Valores por defecto ayudan a tener un comportamiento predecible (limit=10, offset=0).
# schemas.py
from pydantic import BaseModel, Field
from typing import Optional
class SearchParams(BaseModel):
q: Optional[str] = Field(None, description='Texto a buscar en name')
category: Optional[str] = None
min_price: Optional[int] = None
max_price: Optional[int] = None
limit: int = Field(10, gt=0, le=100)
offset: int = Field(0, ge=0)
Paso 4: Implementar la ruta de búsqueda en FastAPI
La ruta acepta query parameters, construye dinámicamente la query con SQLAlchemy y devuelve resultados paginados. Al construir las condiciones con SQLAlchemy evitamos SQL injection. Para proporcionar información de paginación útil puede querer devolver también un campo "total" con el número total de registros que coinciden con los filtros (requiere una query COUNT separada).
# main.py
from fastapi import FastAPI, Depends, HTTPException
from sqlalchemy import create_engine, select, Table, MetaData, and_
from sqlalchemy.sql import text
from sqlalchemy.exc import SQLAlchemyError
from typing import List
from schemas import SearchParams
app = FastAPI()
engine = create_engine('sqlite:///data.db')
metadata = MetaData()
items = Table('items', metadata, autoload_with=engine)
@app.get('/search')
def search(params: SearchParams = Depends()):
try:
stmt = select(items)
conditions = []
if params.q:
conditions.append(items.c.name.ilike(f"%{params.q}%"))
if params.category:
conditions.append(items.c.category == params.category)
if params.min_price is not None:
conditions.append(items.c.price >= params.min_price)
if params.max_price is not None:
conditions.append(items.c.price <= params.max_price)
if conditions:
stmt = stmt.where(and_(*conditions))
stmt = stmt.limit(params.limit).offset(params.offset)
with engine.connect() as conn:
result = conn.execute(stmt).mappings().all()
return {"count": len(result), "results": result}
except SQLAlchemyError as e:
raise HTTPException(status_code=500, detail=str(e))
Paso 5: Ejecutar el servidor y probar localmente
Use Uvicorn para ejecutar la API. FastAPI incluye documentación automática en /docs (Swagger) y /redoc, muy útil para probar de forma interactiva. Ejemplos de llamadas:
uvicorn main:app --reload --port 8000
# Ejemplo de llamada
curl "http://127.0.0.1:8000/search?q=tec&category=Eletrónica&limit=5&offset=0"
Compruebe respuestas JSON con las keys count y results. Pruebe combinaciones: búsqueda por texto, filtro por category, rangos de precio y paginación. En Swagger puede probar varias combinaciones rápidamente.
Paso 6: Manejar errores comunes y mejorar la seguridad
Errores frecuentes: SQL injection (usar SQLAlchemy con parámetros lo evita), parámetros inválidos (pydantic ayuda), timeouts y límites de payload. Para producción, añada autenticación (API key/JWT), límites de rate (por ejemplo 100 peticiones/min por IP), logging y monitorización. También es habitual imponer un límite máximo de limit (por ej. 100) para evitar respuestas demasiado grandes.
# ejemplo simple de verificación de API key
from fastapi import Header
API_KEY = 'trocar_para_prod'
def get_api_key(x_api_key: str = Header(...)):
if x_api_key != API_KEY:
raise HTTPException(status_code=401, detail='Invalid API Key')
return x_api_key
# luego usar Depends(get_api_key) en las rutas
Otras mejoras: configurar CORS adecuadamente, añadir caching (por ejemplo Redis) para resultados populares y usar un pool de conexiones cuando migre a PostgreSQL.
Verificar el resultado
Confirme que la API responde con JSON con las keys count y results. Pruebe varios parámetros: búsqueda por texto, filtros por category, rangos de precio y paginación (limit/offset). Verifique también que al enviar una API key incorrecta recibe 401 y que valores excesivos para limit son rechazados por la validación de pydantic.
Conclusión
Ahora dispone de una API de búsqueda de datos en Python con FastAPI y SQLite, que soporta filtros, paginación y validación. Próximos pasos recomendados: migrar a una base de datos de producción (PostgreSQL) si anticipa alta concurrencia o volúmenes >1M registros, añadir caching con Redis, e integrar autenticación robusta (OAuth/JWT) y logging estructurado. Pruebe añadir ordenación y facets para mejorar la búsqueda — ¿qué ordenación tendría sentido para sus datos?