Boas práticas: paginação e filtros

Continuando com outro post sobre boas práticas no uso de API, hoje vamos falar sobre paginação. Caso você tenha perdido algum dos outros posts, aqui estão eles: HTTP Status e APIs e seus métodos

Paginação de APIs

Sempre que houver a necessidade de retornar mais detalhes sobre qualquer um dos atributos do recurso desejado, o parâmetro de paginação pode ser usado.

Este uso é necessário para evitar que a consulta executada na API fique sobrecarregada, causando um timeout ao utilizar a solicitação em questão. Em geral, para todos os serviços que retornam grandes quantidades de dados, deve-se sempre usar a paginação para retornar os registros.

Junto com a paginação, será necessário indicar a quantidade de informação a ser devolvida em cada página. Portanto, recomenda-se utilizar o parâmetro de tamanho e que este valor seja inferior a 200, dependendo do tipo de consulta e das informações a serem devolvidas de outra forma.

O uso destas informações junto com a consulta executada faz com que o pedido de leitura e retorno backend seja mais rápido, causando assim uma experiência mais agradável e ágil para o desenvolvedor que está consumindo a API.

Ou seja, melhora a experiência do usuário e evita um processamento de informações muito extenso, que pode causar falhas e até mesmo interrupção da leitura (causando timeout, onde o backend não retorna as informações no tempo requerido).

Na prática, um exemplo de como inserir esta informação no endpoint é através da página=0&size=100.

Tenha em mente que estes nomes de campos de parâmetros podem mudar de acordo com a implementação de seu PA (você pode encontrar estes campos como Page and Size; Offset and Limit; Page and PageSize; entre outros).

Utilização de filtros

Outro grande suporte na otimização das consultas de informação é o uso de filtros.

Fornecer este uso dentro de sua implementação também é de grande ajuda quando se trata de uma melhor experiência de uso de APIs.

Através deste recurso, será possível para o desenvolvedor limitar as informações que ele quer ter retornado, otimizando as solicitações executadas especificamente para o que é necessário.

Supondo que, na solicitação, você queira apenas o retorno das informações que estão com o status aprovado, você pode inserir em sua solicitação o status do filtro=aprovado (lembrando sempre que estas nomenclaturas dependerão da implementação de sua API), delimitando assim os retornos apenas para este cenário.

Então, você agora está pronto e ciente de todas as recomendações e métodos certos para fazer o melhor uso dos APIs?!