One Piece API
API publica del universo de One Piece, construida con Hono, TypeScript y Drizzle ORM. Expone personajes, frutas del diablo, afiliaciones y ocupaciones con filtros, paginacion, documentacion OpenAPI y controles de seguridad para despliegue serverless.
Un backend compacto, legible y listo para usarse.
Tests: 27 pasando
Problema
La informacion de One Piece suele estar dispersa, en formatos poco consistentes o pensada para lectura humana. Para apps, bots o dashboards se necesita una fuente consultable, filtrable y estable.
Solucion
Un servicio REST versionado con contrato JSON limpio, busqueda por texto, filtros por dominio, relaciones normalizadas y respuestas paginadas listas para consumir desde frontend o integraciones.
Resultados Tecnicos
Señales objetivas de calidad revisadas en el codigo.
Test con Vitest
27/27
Validadores, servicios, cache, CORS, errores, ETags y Swagger UI.
Contrato publico
OpenAPI
Documentacion servida desde https://one-piece-api-azure.vercel.app/api/v1.
Seguridad base
Headers + CORS
Secure headers, origenes configurables y errores seguros en produccion.
Performance
Cache + ETag
Cache-aside con usando redis desde upstash y ETags para respuestas condicionales.
Endpoints Principales
Superficie publica versionada y organizada por recursos del dominio.
Personajes
/personajes Listado paginado con filtros por raza, estado, canon, tripulacion, ocupacion, fruta y busqueda libre.
Frutas del Diablo
/frutas Consulta por tipo, subtipo Zoan y texto libre, incluyendo consumidores relacionados.
Busqueda directa
/buscar/:nombre Acceso por nombre exacto o coincidencia parcial escapando patrones LIKE para evitar wildcard injection.
Catalogos
/afiliaciones Listas normalizadas para alimentar filtros, selects y experiencias de exploracion.
Arquitectura
Capas simples, responsabilidades claras y dependencias externas separadas.
HTTP Layer
Hono monta rutas bajo /api/v1, aplica
middleware global y adapta el handler a Vercel
serverless.
Application Layer
Servicios formatean DTOs, aplican cache-aside y devuelven respuestas paginadas consistentes.
Data Layer
Repositorios encapsulan Drizzle queries sobre un modelo relacional con tablas puente para frutas, afiliaciones y ocupaciones.
Diagrama Interactivo
Flujo desde consumidor HTTP hasta la base de datos, incluyendo middleware, servicios, repositorios y cache.
Flujo de Request
De una consulta publica a una respuesta JSON consistente.
Entrada versionada
La request entra por /api/v1 y Vercel la resuelve con el handler de Hono.
Middleware transversal
Se aplican secure headers, compresion, ETag, CORS configurable y rate limit cuando Upstash esta disponible.
Validacion
Zod normaliza query params, limita paginacion y valida ids, nombres y enums antes de tocar la base de datos.
Servicio + repositorio
El servicio intenta cache, consulta el repositorio si hace falta, aplana relaciones y arma el envelope de respuesta.
Respuesta JSON
La API devuelve data y, en listados, metadata de paginacion con total,
limit, offset y hasNext.
Patrones de Diseño
Decisiones que mantienen la API simple de evolucionar.
Repository Pattern
Las rutas no conocen SQL. Los repositorios concentran queries, joins, filtros y conteos, dejando la logica de caso de uso en servicios.
Middleware Chain
Seguridad, cache HTTP, compresion, CORS y rate limit se aplican de forma transversal sin duplicar logica en cada endpoint.
DTO Formatting
Las tablas puente se aplanan antes de salir al cliente, entregando contratos JSON ergonomicos y estables.
Cache-Aside
Upstash acelera lecturas frecuentes y la API degrada de forma controlada cuando Redis no esta configurado.
Despliegue y Producción
Detalles del entorno productivo y checklist de lanzamiento completado.
Infraestructura y Configuración
- → Desplegado en Vercel Serverless con Hono.
- → Base de datos en Neon Postgres con Drizzle ORM.
- → Cache-aside implementado usando Upstash Redis.
- → Variables
de entorno (
DATABASE_URL,ALLOWED_ORIGINS, etc.) configuradas de forma segura.
Checklist Completado
- → Migraciones
e índices trigram (
pg_trgm) aplicados en producción. - → Tests con Vitest (27/27) y typecheck en TypeScript validados.
- → CORS configurable y secure headers activos.
- → Entorno
limpio con manejo seguro de errores (
NODE_ENV=production).
Posibles Mejoras
Iteraciones que elevarian el proyecto de demo solida a API publica mas madura.
DX y despliegue
- README con ejemplos curl y parametros de filtro.
- .env.example con variables obligatorias y opcionales.
- Script de migration/check antes de deploy.
Observabilidad
- Endpoint health/readiness que valide conexion a DB.
- Request id por log para seguir errores en Vercel.
- Metricas de cache hit/miss y rate limit.
Contrato API
- Generar OpenAPI desde schemas para evitar drift.
- Agregar respuestas 400/429/500 documentadas.
- Tests de repositorio con una base temporal.