Parâmetros de consulta comuns

Os endpoints de listagem do WEEGLOO (GET que retornam uma coleção, como GET /spaces/{spaceId}/contents) aceitam parâmetros de consulta comuns. Com esses parâmetros você limita a quantidade de itens trazidos por página, define o critério de ordenação, traz recursos relacionados em conjunto, recebe apenas os campos necessários, restringe a lista por condições e navega para a página seguinte ou anterior.

Esses parâmetros funcionam da mesma forma independentemente do tipo de recurso. As referências de cada recurso descrevem apenas as condições específicas daquele recurso e remetem a esta página para os parâmetros comuns aqui tratados.

Parâmetros

Os tipos de campo sys usados em order e select podem ser consultados em Propriedades de sistema (sys).

Filtros

As condições de filtro não são envolvidas em filter[]; são enviadas diretamente como parâmetros de consulta. O formato é {campo}[{operador}]={valor}, e, se você omitir o operador, ele é interpretado como eq. Para o conjunto completo de operadores disponíveis, consulte Operadores abaixo.

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

Por exemplo, para trazer apenas os itens cujo name começa com garrafa térmica, envie name[prefix]=garrafa térmica. As regras e os pontos de atenção são os seguintes.

• Não envolva as condições em filter[]. Envolver, como em filter[name[prefix]]=garrafa térmica, não funciona.
• Várias condições são combinadas com AND. Restam apenas os itens que satisfazem todas elas; a busca OR, em que basta satisfazer uma entre várias condições, não é suportada. Para acertar um entre vários valores em um mesmo campo, use in.
• Uma condição fields. inclui o locale. Por exemplo, fields.file.ko-KR.mimeGroups=Image mantém apenas os arquivos de imagem em uma lista de Media, e sys.createdAt[gte]=2026-06-01T00:00:00Z mantém apenas os itens criados após aquele momento.
• Filtrar ou ordenar uma lista de Content por uma condição fields. também exige o Content Type. Envie sys.contentType.sys.id em conjunto (apenas na lista plana /contents); um contentType= simples não o substitui. Consulte a referência de Content para mais detalhes.

Operadores

Os campos RichText e Json não são pesquisáveis e não podem ser usados em condições de filtro.

Busca avançada (Advanced Search)

Os operadores regex, near e within e a busca de texto completo sobre texto funcionam apenas na busca avançada. A busca avançada é ativada adicionando o cabeçalho X-Weegloo-Advanced-Search: true à requisição de listagem, e o mesmo cabeçalho vem na resposta.

• Busca de texto completo: ao usar eq em um campo de texto (LongText) com a busca de texto completo ativada, em vez de encontrar apenas o valor exatamente igual, ele encontra também os itens que contêm aquele valor, com correspondência parcial ou aproximada. Se a busca avançada não estiver ativada ou se o plano não oferecer busca avançada, o mesmo eq funciona como correspondência exata.
• Busca por Location: near (raio) e within (polígono) só se usam em campos Location e só funcionam na busca avançada.
• Se você enviar regex, near ou within em uma requisição que não pode usar a busca avançada, eles não são aceitos.

Paginação (cursor)

O corpo da resposta de listagem contém um objeto links, e dentro dele estão next e prev. links.next é o caminho completo para a página seguinte.

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

Há duas formas de trazer a página seguinte. Chame diretamente o caminho de links.next, ou extraia o valor do cursor next de links.next e passe-o como parâmetro next na próxima requisição. Se links.next não existir, esta é a última página. Para a página anterior, navegue da mesma forma com links.prev.

Não aumente o skip para avançar páginas. Se itens forem adicionados ou removidos entre as listagens, a posição do skip fica desalinhada e itens podem ser pulados ou duplicados. O cursor (next, prev) não tem esse problema.

A seguir, um exemplo da estrutura de uma resposta de listagem. O sys.type do invólucro é TotalPageResponse, items contém o array de itens e links contém os caminhos de navegação.

{
  "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 é o número total de itens que atendem às condições, e limit é o tamanho de página aplicado a esta resposta. items contém apenas os itens correspondentes àquela página.

Documentos relacionados

• Propriedades de sistema (sys): os campos sys usados em order e select.
• Convenções: tipo de mídia, JSON Patch, concorrência.