Express.js
Explica cómo diseñar endpoints de colección con filtros permitidos, orden estable, límites y paginación por offset o cursor sin acoplar el contrato al ORM.
Una colección HTTP necesita límites, orden estable y una traducción segura hacia la base de datos. Sin ese contrato, el coste y los resultados se vuelven impredecibles.
Paginación, filtros y ordenamiento forman un pequeño lenguaje público. El cliente no debe controlar columnas, operadores o joins internos directamente.
GET /orders?status=pending&limit=25&sort=-createdAt&cursor=...Devolver una tabla completa:
La paginación limita trabajo por request y crea navegación predecible.
SELECT * FROM orders
WHERE branch_id = $1
ORDER BY created_at DESC, id DESC
LIMIT $2 OFFSET $3;Es simple y permite saltar a una página, pero offsets profundos obligan al motor a recorrer y descartar filas. Además, inserciones entre requests pueden desplazar resultados.
SELECT * FROM orders
WHERE branch_id = $1
AND (created_at, id) < ($2, $3)
ORDER BY created_at DESC, id DESC
LIMIT $4;El cursor representa la última posición. Es eficiente para scroll continuo y estable ante inserciones anteriores, pero no salta fácilmente a “página 40”.
ORDER BY created_at DESC puede empatar. Añade un tiebreaker único:
created_at DESC, id DESCEl cursor debe incluir ambas partes. Sin orden total, pueden aparecer duplicados o faltantes.
No obligues al cliente a construir detalles internos. Codifica y firma una estructura:
const cursor = Buffer.from(JSON.stringify({ createdAt, id })).toString('base64url');En producción valida versión, formato y relación con filtros. Un cursor no debe permitir cambiar tenant o escapar del scope.
Define una whitelist:
const querySchema = z.object({
status: z.enum(['pending', 'confirmed', 'cancelled']).optional(),
customerId: z.string().uuid().optional(),
limit: z.coerce.number().int().min(1).max(100).default(25),
sort: z.enum(['createdAt', '-createdAt']).default('-createdAt'),
cursor: z.string().optional(),
}).strict();Cada filtro público se traduce a una expresión conocida. No pases req.query al ORM como where completo.
Los placeholders SQL no representan identifiers. Mapea opciones públicas:
const sorts = {
createdAt: sql`created_at ASC, id ASC`,
'-createdAt': sql`created_at DESC, id DESC`,
} as const;Nunca interpoles el nombre recibido.
{
"data": [],
"page": {
"nextCursor": "opaque-value",
"hasMore": false
}
}No necesitas contar todas las filas para cada request. Un total exacto puede ser costoso; ofrece count solo cuando el producto lo requiere.
El scope de autorización precede a filtros del cliente:
tenant/branch permitido
AND filtros públicosUn cliente no debe quitar el filtro de tenant mediante query params.
La API y los índices deben evolucionar juntos. Un endpoint que filtra por branch_id, status y ordena por fecha puede necesitar un índice compuesto apropiado. No crees uno por cada combinación sin medir.
Offset: backoffice pequeño, navegación por páginas y datasets limitados.
Keyset: feeds, pedidos crecientes, APIs públicas y recorridos secuenciales.
A veces una aplicación ofrece ambas en endpoints distintos.
Prueba empates, inserciones entre páginas, filtros combinados, cursor manipulado, aislamiento por tenant, límites máximos y ausencia de duplicados.
Diseño de APIs REST pragmáticas conecta recursos, métodos y contratos sin convertir REST en dogma.