Paginação, Ordenação e Filtros em APIs RESTFul

Técnico

Fala amigos hackers, chegamos a mais um artigo sobre APIs.

E o tema de hoje é paginação, ordenação e filtros, algo imprescindível no design de uma API.

Lembra daquela API com dados de gastronomia dos primeiros artigos da série:

https://api.minhagastronomia.com

Se você não leu os primeiros artigos, dá uma lida para ficar 100% atualizado:

Então vamos lá, imaginem que agora essa API já está com muitos dados, e que ao fazer um GET de vinhos, ela me retorne mais que 10 mil registros, e isso está demorando muito para retornar aos clients que consomem esse recurso.

É exatamente isso que a paginação, a ordenação e os filtros resolvem…

Em resumo, é a implementação capaz de fazer sua API trabalhar de forma mais eficiente com os dados na comunicação entre client e server, trafegando apenas o necessário!

Para facilitar a visão, vou listar aqui os principais motivos de você implementar esses conceitos:

Experiência do client

Como você estará fragmentando o resultado no server, a resposta da mensagem trafegada fica bem menor, e por isso, o client consegue o resultado da requisição muito mais rápido, criando uma experiência agradável em termos de performance ao desenvolvedor que está consumindo a API.

Utilização inteligente de infraestrutura

Como o consumo dos dados fica sob demanda, isso ajuda muito na escalabilidade vertifical e horizontal de uma API. Na prática, esse modelo utiliza recursos de infraestrutura de forma mais inteligente.

Chega de teorias, agora vamos analisar os principais tipos utilizados no mercado.

Paginação

Cursor

A paginação baseada em cursor funciona por uma chave única e sequencial que indica a partir de que registro os dados serão retornados.

Em outras palavras, imaginem que você quer os registros a partir do vinho de ID 156 até o ID 200. Então, você faria a seguinte requisição:

HTTP GET
https://api.minhagastronomia/vinhos?since_id=156&max_id=200

Notem que foram adicionados os parâmetros since_id e max_id, que nesse caso, são os cursores de navegação dentro da API, e que delimitam os resultados a serem retornados pela requisição.

Normalmente as APIs com paginação baseadas em cursores, retornam no resultado da requisição os parâmetros para navegação da página anterior, e também da próxima.

OBS: O nome dos parâmetros de cursores podem mudar de acordo com a implementação da API.

Page e PageSize

A paginação baseada em page e pagesize, como o próprio nome já diz, é utilizada através dos parâmetros de número da página a ser navegada e o seu respectivo tamanho (em número de registros).

Vamos supor que quer os dados de 10 vinhos da terceira página, então você faria a seguinte requisição:

HTTP GET
https://api.minhagastronomia/vinhos?page=3&page_size=10

OBS: O nome dos parâmetros podem mudar de acordo com a implementação da API.

Offset e Limit

A paginação baseada em offset e limit é utilizada a partir de um deslocamento de registros.

Em outras palavras, você especifica no offset a partir de qual registro você quer os dados, e no limit você especifica o limite de registros a serem retornados.

Agora vamos imaginar que você quer 30 vinhos a partir do décimo registro, então você faria a seguinte requisição:

HTTP GET
https://api.minhagastronomia/vinhos?offset=10&limit=30

Filtros e Ordenação

Sobre filtros e ordenação não tem muito segredo, via parâmetros de query string você consegue dar mais inteligência a sua API, além de dar mais capacidade ao client para trabalhar com os dados sob demanda.

Exemplo prático de filtro:

HTTP GET
https://api.minhagastronomia/vinhos?pais=Brasil&estado=RS&de_preco=100&ate_preco=200&status=disponivel

No exemplo acima, estou solicitando todos os vinhos do Brasil, do estado do Rio Grande do Sul, com o preço entre 100 e 200 reais e que estão disponíveis para compra.

Também temos a possibilidade de utilizar alias para filtros muito utilizados, por exemplo:

HTTP GET
https://api.minhagastronomia/vinhos/disponiveis?estado=RS&de_preco=100&ate_preco=200

Nesse caso, eu utilizo o sub-recurso “disponiveis” que contém o filtro pré-estruturado, e facilita o consumo do desenvolvedor.

Exemplo prático de ordenação:

HTTP GET
https://api.minhagastronomia/vinhos?sort=pais:asc,estado

No exemplo acima, notem que eu inclui o parâmetro sort” que contémo campo chave da ordenação seguido por :” para especificar se quero os dados em ordem ascendente ou descendente, além da vírgula de separação dos camposque eu e uma separação por vírgula

Esse não é o único padrão dessa técnica, mas particularmente acho bem clean.

Boas práticas

Offset e limit com filtros de “range”

Minha recomendação é a utilização da técnica offset e limit para paginação, pois além de ser o método mais utilizado ultimamente, é o que proporciona melhor experiência ao consumidor da API.

A navegação por page e page size, requer recálculos das páginas em cenários de mudança do page size, e isso acaba criando uma complexidade adicional e que prejudica a experiência do desenvolvedor.

E se você for utilizar page e page size, por favor, especifique na sua documentação em que página é iniciada a busca dos dados, pois já vi inúmeros casos de que a página 0 e 1, retornam os mesmos registros!

Tenha default values

Tenha valores padrões em parâmetros de paginação, como por exemplo, limitpadrão de 500 objetos, e limit máximo de 1000 objetos, dessa forma, além de você facilitar o consumo em casos do client não enviar o parâmetro, você também protege a performance e escalabilidade da sua API.

Não exagere em parâmetros de Query String

Minha recomendação nesse assunto é que você não exagere em parâmetros de query string, ou seja, faça uma análise do que realmente faz sentido, caso contrário, você estará poluindo a URL desnecessariamente, e deixando tudo mais complexo para o desenvolvedor que irá consumir a API.

Outro ponto importante também é não colocar parâmetros como obrigatórios casos que não fazem sentido, por exemplo:

HTTP GET
https://api.minhagastronomia/vinhos?pais=Brasil&estado=RS&de_preco=100&ate_preco=200&status=disponivel

Imaginem que nessa requisição acima o parâmetro de status fosse obrigatório, isso não faria o menor sentido, pois, caso eu quisesse todos os vinhos independente do status, eu teria que concatenar diversas requisições.

Em outras palavras, através da obrigatoriedade de um parâmetro, eu criei uma experiência ruim no consumo da minha API.

E por último, pense sempre em casos de uso da sua API quando for criar um novo recurso, isso irá facilitar bastante na definição dos parâmetros e dos metadados.

Compartilhe

O melhor sobre APIs e Integrações.
Toda semana no seu inbox.

Fique por dentro das novidades e melhores práticas

use o linkapi agora!

Construa integrações gratuitamente

use o linkapi agora

Construa integrações gratuitamente

Thiago Lima

Thiago Lima

Thiago Lima é o CEO e fundador da LinkApi. Programador desde os 12 anos e empreendedor desde os 17, é referência no assunto de APIs e Integrações, carreiras para desenvolvedores e empreendedorismo.
    O melhor sobre APIs e Integrações. Toda semana no seu inbox.

    O melhor sobre APIs e Integrações.

    Toda semana no seu inbox.

    Conteúdos técnicos, novidades sobre integrações, dicas de mercado e mais conteúdos exclusivos!

    Assinatura realizada com sucesso!

    Pin It on Pinterest