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.
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, limit padrã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.
Quer continuar a nossa série? Leia nossos outros artigos sobre APIs!
