Pular para o conteúdo principal

Paginação, filtros e ordenação

Nessa página detalharemos o padrão de paginação, filtro e ordenação.

Paginação

Em todas as operações de consultas que retornem listas, a aplicação fornece um mecanismo de paginação. Existem dois parâmetros: limit e offset. Ambos os parâmetros definem o tamanho do bloco dos resultados. Isso evita consumo excessivo de recursos do servidor e do client, além de otimizar a visualização da informação pelo usuário final.

Parâmetros da chamada

ParâmetroDescriçãoValor Padrão
_limitDetermina a quantidade de registros a serem retornados50
_offsetPosição do registro de referência, a partir dele serão retornados os próximos N registros0

Exemplo:

GET /v1/orders?_offset=150&_limit=20

Parâmetros da resposta

ParâmetroDescriçãoValor Padrão
limitRetorna a quantidade específica de registros se houver50
countQuantidade de registros que foi retornada nessa página0
max_limitRefere-se ao valor máximo que pode ser utilizado no campo limit0

Resposta:

{
"page": {
"limit": 20,
"offset": 150,
"count": 1,
"max_limit": 10
}
}

Na consulta acima, a partir do registro #151, serão retornados os próximos 20 registros.

Para a demonstração vamos definir que o valor padrão é 50 e o valor máximo 200.

ExemploResultado
/v1/orders?_offset=150&_limit=20Serão retornados os próximos 20 registros, a partir do registro #151
/v1/orders?_offset=0Serão retornados os próximos 50 registros, a partir do primeiro registro
/v1/orders?_offset=0&_limit=1Será retornado o primero registro
/v1/orders?_offset=0&_limit=51Serão retornados os próximos 51 registros, a partir do primeiro registro
/v1/orders?_offset=0&_limit=200Serão retornados os próximos 200 registros, a partir do primeiro registro

Ordenação

A aplicação fornece a possibilidade de ordenar os valores das listagens, nos sentidos ascendente e descendente:

IdentificadorOrdemExemplo
?_sort=campo:ascAscendenteGET /v1/orders?_sort=shipping.date:asc
?_sort=campo:descDescendenteGET /v1/orders?_sort=shipping.date:desc
info

Se não for especificado uma ordem após o nome do campo, é aplicada uma ordenação asc.

Ordenações com combinação de campos

Mais do que um critério de ordenação pode ser especificado na mesma URL:

?_sort=campo1:asc,campo2:desc,campo3:asc

Quando os critérios são combinados, a regra de ordenação é aplicada uma sobre a outra, da esquerda para a direita.

Filtragem

atenção

Os campos de filtro apresentados nesta seção representam um padrão geral e podem ou não estar disponíveis em endpoints que implementam paginação. A disponibilidade e os critérios específicos de filtragem para cada endpoint devem ser consultados diretamente na documentação do respectivo endpoint.

Pesquisas

A aplicação tem mecanismos para que a coleção possa ser consultada através de filtros de busca. Esses critérios são sempre expressos na URL através de parâmetros de consulta.

info

Neste caso, a aplicação utiliza os nomes dos campos com todos os caracteres em minúsculo.

IdentificadorCritérioExemplo
?campo=valorValor exatoGET /foo/bar?branch.id=175&code=ABC
?campo__like=valorValor parcial (like)GET /foo/bar?customer.name__like=Ana
?campo__in=valor_1,valor_2,valor_XLista de valores (in)GET /foo/bar?branch.id__in=175,215,830
?campo__gt=valorMaior que (>)GET /foo/bar?amount__gt=100
?campo__gte=valorMaior ou igual a (>=)GET /foo/bar?amount__gte=100
?campo__lt=valorMenor que (<)GET /foo/bar?amount__lt=100
?campo__lte=valorMenor ou igual a (=<)GET /foo/bar?amount__lte=100
info
  • Para fazer uso da função between, a aplicação utiliza Maior que ou Maior igual a e Menor que ou Menor ou igual a.
  • Os critérios se somam como um AND.

Quando a pesquisa envolver campos que estão modelados como objetos no body, a aplicação faz a referência através do caminho completo até o atributo - utilizando o separador ponto.

Por exemplo, para o seguinte body JSON:

{
"customer": {
"id": 1000,
"name": "..."
},
"branch": {
"id": 595
}
}

A pesquisa seria assim:

GET /foo/bar?customer.id=1000&branch.id=595

Resposta:

{
"meta": {
"page": {
"limit": 10,
"offset": 0,
"count": 1,
"max_limit": 10
},
"links": {
"previous": "/foo/bar?_limit=10&_offset=0",
"self": "/foo/bar?_limit=10&_offset=10",
"next": "/foo/bar?_limit=10&_offset=20"
}
},
"results": [
{
"sku": "ABC1232fd",
"channel": "magalu",
"quantity": 1.5,
"unit": "unit"
}
]
}

O campo results retorna os dados esperados. O campo meta retorna as informações sobre as quantidades de registros encontrados, onde apenas o campo total é opcional. Os filtros aplicados na consulta, retornam o campo utilizado como filtro, o operador utilizado sendo representado pelos nomes: eq, like, in, gt, gte, lt, lte e o valor aplicado.

As ordenações identificam o campo e a ordenação (asc e desc) que foi aplicada, e as URLs de paginação, para obter os próximos registros ou os anteriores, se existirem, como a própria URL que foi consultada.

atenção

Limitações com parâmetros de consulta

A RFC do HTTP 1.1 não limita a quantidade de caracteres na URI, como pode ser verificado nos links:

No desenho de APIs sugerimos cautela ao utilizar URIs muito longas. Em geral, URIs muito longas são indicativos de que sua API pode não estar aderente aos padrões de mercado. A aplicação sugere modelar de alguma outra forma de maneira que se adeque ao padrão REST.

Em alguns casos pode-se encontrar restrições no servidor Web por motivo de segurança ou configuração fina de performance, em geral o parse pode causar lentidão no servidor.