Nuestra API está construida con Hono en Cloudflare Workers, optimizando para baja latencia y distribución global. Así es como la construimos y mantenemos.

Framework Hono

Elegimos Hono por su pequeña huella y diseño con prioridad en el borde:

Paquete pequeño: Hono agrega una sobrecarga mínima al tamaño del Worker, manteniendo los arranques en frío rápidos.
Patrones familiares: El enrutamiento similar a Express facilita la incorporación de los desarrolladores.
Middleware integrado: CORS, compresión y registro de logs funcionan de fábrica.
Seguridad de tipos: Soporte completo de TypeScript con tipado de solicitudes y respuestas.

Diseño con prioridad en el borde

Cada decisión de API considera las restricciones del despliegue en el borde:

Manejadores sin estado: Sin sesiones en el servidor ni almacenamiento local entre solicitudes.
Estado externo: Todo el estado vive en Supabase (SQL), Cloudflare KV (clave-valor) o R2 (blobs).
Optimización de arranque en frío: Inicialización diferida de clientes pesados (Stripe, Supabase) solo cuando se necesitan.
Enrutamiento regional: Cloudflare enruta automáticamente las solicitudes a la ubicación de borde más cercana.

Validación de solicitudes

Zod proporciona seguridad de tipos en tiempo de ejecución para todos los datos entrantes:

Definiciones de esquema: Cada endpoint define la forma de entrada esperada con esquemas Zod.
Análisis automático: Las solicitudes inválidas fallan rápidamente con mensajes de error claros.
Inferencia de tipos: Los tipos TypeScript se derivan de los esquemas, garantizando la consistencia.
Transformaciones: Zod maneja la coerción (cadena a número) y los valores predeterminados de forma limpia.

Manejo de errores

Las respuestas de error consistentes facilitan la depuración:

Formato estructurado: Todos los errores devuelven JSON con error, message y detalles opcionales.
Códigos de estado HTTP: Usamos códigos apropiados (400 para validación, 401 para autenticación, 403 para permisos, 429 para límite de velocidad).
Seguimiento de errores: Las excepciones se registran con contexto de la solicitud para la depuración.
Mensajes amigables para el usuario: Los detalles técnicos se registran pero no se exponen a los clientes.

Limitación de velocidad

Nuestra estrategia de limitación de velocidad protege el sistema siendo justa:

Límites escalonados: Diferentes límites para endpoints de seguimiento (alto), endpoints de API (medio) y endpoints de autenticación (bajo).
Seguimiento por clave: Las claves de API tienen cuotas individuales basadas en el nivel de suscripción.
Ventana deslizante: Los límites se calculan sobre ventanas de tiempo continuas, no períodos fijos.
Degradación elegante: Las solicitudes con límite de velocidad reciben encabezados Retry-After.

Organización de endpoints

Las rutas están organizadas por dominio para la mantenibilidad:

/e/:trackingCode — Seguimiento público (amigable con bloqueadores de anuncios)
/api/analytics/* — Consultas de datos del tablero
/api/replay/* — Gestión de reproducción de sesiones
/api/billing/* — Integración con Stripe
/api/team/:teamId/* — Operaciones con alcance de equipo
/api/external/v1/* — Acceso de API de terceros
/api/cron/* — Disparadores de tareas programadas (autenticación por webhook)