Consultas

Todos los endpoints de listado de la API admiten un conjunto común de parámetros de consulta para paginación, ordenamiento y filtrado.

Parámetros comunes

Parámetro	Tipo	Descripción
`page`	`number`	El número de página a obtener (predeterminado: 1).
`limit`	`number`	La cantidad de elementos por página (predeterminado: 10).
`sort`	`string`	El campo por el que ordenar. Antepone `-` para orden descendente (p. ej., `-createdAt`).
`where`	`object`	Objeto de consulta para filtrar resultados con operadores.

Respuesta de paginación

Todos los endpoints de listado devuelven una respuesta paginada con la siguiente estructura:


{
  "docs": [...],
  "totalDocs": number,
  "limit": number,
  "totalPages": number,
  "page": number,
  "pagingCounter": number,
  "hasPrevPage": boolean,
  "hasNextPage": boolean,
  "prevPage": number | null,
  "nextPage": number | null
}

Ordenamiento

Usa el parámetro sort para ordenar los resultados por un campo concreto.

Dirección de ordenamiento

Ascendente (predeterminado): ?sort=createdAt
Descendente: Antepone - → ?sort=-createdAt

Campos ordenables

Puedes ordenar por cualquier campo de primer nivel del objeto. Ejemplos habituales:

Campo	Descripción
`createdAt`	Ordenar por fecha de creación
`updatedAt`	Ordenar por fecha de última modificación
`title`	Ordenar alfabéticamente por título

Ejemplos

Más recientes primero:


?sort=-createdAt

Más antiguos primero:


?sort=createdAt

Alfabéticamente por título:


?sort=title

Operadores Where

El parámetro where acepta un objeto de consulta que te permite filtrar resultados con varios operadores:

Operador	Descripción
`equals`	El valor debe ser exactamente igual.
`not_equals`	Devuelve todos los documentos donde el valor no es igual.
`greater_than`	Para campos numéricos o basados en fecha.
`greater_than_equal`	Para campos numéricos o basados en fecha.
`less_than`	Para campos numéricos o basados en fecha.
`less_than_equal`	Para campos numéricos o basados en fecha.
`like`	La cadena debe estar presente sin distinguir mayúsculas. Si es una cadena de varias palabras, todas deben estar presentes, en cualquier orden.
`contains`	Debe contener el valor introducido, sin distinguir mayúsculas.
`in`	El valor debe estar en la lista de valores separados por comas proporcionada.
`not_in`	El valor NO debe estar en la lista de valores separados por comas proporcionada.
`exists`	Solo devuelve documentos donde el valor existe (`true`) o no existe (`false`).

Lógica And / Or

Puedes combinar varias consultas con lógica and / or. Se pueden anidar al nivel que necesites para crear consultas complejas.

Ejemplos de consultas

Filtrar por valor exacto:


?where[status][equals]=COMPLETE

Filtrar por valor que contiene una cadena:


?where[title][contains]=tutorial

Filtrar por fecha (mayor que):


?where[createdAt][greater_than]=2024-01-01

Filtrar donde existe un campo:


?where[description][exists]=true

Usar lógica OR:


?where[or][0][status][equals]=COMPLETE&where[or][1][status][equals]=PROCESSING

Usar lógica AND:


?where[and][0][status][equals]=COMPLETE&where[and][1][visibility][equals]=private

Uso del paquete qs

Las consultas complejas pueden resultar difíciles de escribir como cadenas de consulta. Recomendamos usar el paquete qs-esm para convertir objetos JSON en cadenas de consulta:


import { stringify } from 'qs-esm';
 
const query = stringify({
  where: {
    status: {
      equals: 'COMPLETE'
    },
    and: [
      { visibility: { equals: 'private' } },
      { createdAt: { greater_than: '2024-01-01' } }
    ]
  },
  limit: 20,
  page: 1
}, { addQueryPrefix: true });
 
// Result: ?where[status][equals]=COMPLETE&where[and][0][visibility][equals]=private&where[and][1][createdAt][greater_than]=2024-01-01&limit=20&page=1

Este enfoque facilita mucho construir y mantener consultas complejas de forma programática.