Parámetros de consulta comunes

Los endpoints de consulta de listas de WEEGLOO (los GET que devuelven una colección, como GET /spaces/{spaceId}/contents) aceptan parámetros de consulta comunes. Con estos parámetros se limita el número de elementos que se traen en una página, se define el criterio de ordenación, se traen recursos relacionados, se seleccionan solo los campos necesarios, se acota la lista mediante condiciones y se navega a la página siguiente o anterior.

Estos parámetros funcionan de la misma manera con independencia del tipo de recurso. La referencia de cada recurso describe por separado solo las condiciones propias de ese recurso, y para los parámetros comunes que se tratan aquí remite a esta página.

Parámetros

Los tipos de campo sys que se usan en order y select se pueden consultar en Propiedades del sistema (sys).

Filtro

Las condiciones de filtro no se envuelven en filter[], sino que se envían directamente como parámetros de consulta. El formato es {campo}[{operador}]={valor}, y si se omite el operador se interpreta como eq. Consulta el conjunto completo de operadores disponibles en Operadores más abajo.

{campo}[{operador}]={valor}

Por ejemplo, para traer solo los elementos cuyo name empieza por vaso térmico se envía name[prefix]=vaso térmico. Las reglas y advertencias son las siguientes.

• No se envuelven las condiciones en filter[]. Envolverlas como filter[name[prefix]]=vaso térmico no funciona.
• Varias condiciones se combinan con AND. Solo quedan los elementos que cumplen todas; no se admite la búsqueda OR, en la que basta con cumplir una de varias condiciones. Para que un mismo campo coincida con uno de varios valores se usa in.
• Una condición fields. incluye el locale. Por ejemplo, fields.file.ko-KR.mimeGroups=Image deja solo los archivos de imagen en una lista de Media, y sys.createdAt[gte]=2026-06-01T00:00:00Z deja solo los elementos creados después de ese momento.
• Filtrar u ordenar una lista de Content por una condición fields. requiere además el Content Type. Hay que enviar también sys.contentType.sys.id (solo en la lista plana /contents); un simple contentType= no lo sustituye. Para más detalles, consulta la referencia de Content.

Operadores

Los campos RichText y Json no son objeto de búsqueda, por lo que no se pueden usar en condiciones de filtro.

Búsqueda avanzada (Advanced Search)

Los operadores regex, near y within y la búsqueda de texto completo solo funcionan en la búsqueda avanzada. La búsqueda avanzada se activa añadiendo a la solicitud de consulta de listas la cabecera X-Weegloo-Advanced-Search: true, y la respuesta también la incluye.

• Búsqueda de texto completo: si se usa eq en un campo de texto (LongText) que tiene activada la búsqueda de texto completo, no se buscan los elementos exactamente iguales, sino también aquellos que contienen ese valor, mediante coincidencia parcial o aproximada. Si no se ha activado la búsqueda avanzada o el plan no la ofrece, el mismo eq funciona como coincidencia exacta.
• Búsqueda de Location: near (radio) y within (polígono) solo se usan en campos Location y solo funcionan en la búsqueda avanzada.
• Si se envían regex, near o within en una solicitud que no puede usar la búsqueda avanzada, no se aceptan.

Paginación (cursor)

El cuerpo de la respuesta de una lista contiene un objeto links, y dentro de él están next y prev. links.next es la ruta completa que lleva a la página siguiente.

/v1/spaces/HnQ32YiH/contents?limit=15&next=<cursor>

Hay dos maneras de traer la página siguiente. Se llama directamente a la ruta de links.next, o se extrae el valor del cursor next de links.next y se pasa como parámetro next de la siguiente solicitud. Si no hay links.next, es la última página. A la página anterior se navega de la misma manera con links.prev.

Al pasar de página, no aumentes skip. Si se añaden o eliminan elementos entre una consulta y otra, la posición de skip se desfasa y pueden omitirse o duplicarse elementos. El cursor (next/prev) no tiene este problema.

A continuación se muestra un ejemplo de la estructura de una respuesta de lista. El sys.type del envoltorio es TotalPageResponse, en items está el array de elementos y en links están las rutas de navegación.

{
  "sys": { "type": "TotalPageResponse" },
  "limit": 15,
  "totalCount": 42,
  "items": [
    {
      "sys": {
        "id": "3trmXRM3RqbgSnifyg7PUl8DzDgDzP",
        "type": "Content",
        "space": { "sys": { "id": "HnQ32YiH", "type": "Refer", "targetType": "Space" } },
        "createdAt": "2026-06-18T09:51:14.597Z",
        "updatedAt": "2026-06-18T09:51:44.128Z",
        "version": 2,
        "status": "Published"
      }
    }
  ],
  "links": {
    "self": "/v1/spaces/HnQ32YiH/contents?limit=15",
    "next": "/v1/spaces/HnQ32YiH/contents?limit=15&next=Q3Vyc29yVmFsdWU"
  }
}

totalCount es el número total de elementos que cumplen las condiciones, y limit es el tamaño de página aplicado a esta respuesta. En items solo se incluyen los elementos correspondientes a esa página.

Documentos relacionados

• Propiedades del sistema (sys): los campos sys que se usan en order y select.
• Convenciones: tipo de medio, JSON Patch y concurrencia.