O que é a paginação de uma API e por que ela evita respostas enormes?

Publicado em 2026-10-20 por frfrand

Paginación de APIs con limit/offset y cursores: cómo devolver listas grandes, manejar cambios de datos y evitar errores de rendimiento.

A paginação permite devolver uma lista de dados por partes em vez de enviar todos os registros de uma só vez. É comum em catálogos, históricos de pedidos e APIs com milhares ou milhões de elementos.

Se uma loja tem dois milhões de produtos, baixar todo o banco de dados cada vez que alguém abre o catálogo não parece uma boa ideia.

A comparação com uma biblioteca

Imagine que você peça livros de programação. A bibliotecária não esvazia todas as prateleiras em cima da mesa. Ela mostra uma seleção e permite que você passe para os próximos resultados.

Uma API paginada faz algo parecido: recebe informações sobre quanto retornar e a partir de qual ponto continuar.

A paginação por limit e offset

Uma API poderia oferecer:

GET /api/productos?limit=20&offset=40

Isso solicita até vinte produtos a partir de uma determinada posição. É simples de implementar e permite construir páginas tradicionais: primeira, segunda, terceira.

Mas tem limites. Com muitas linhas, algumas consultas com offset elevado podem ser custosas. E se produtos forem adicionados ou removidos entre as solicitações, o usuário pode ver registros repetidos ou pular outros.

Por isso, não se deve assumir que a «página 4» identifica permanentemente o mesmo conjunto de dados.

Paginacao por cursor

Outra técnica utiliza um cursor que representa uma posição lógica de continuação. A resposta pode incluir uma lista e um valor como next_cursor.

O cliente envia esse cursor para recuperar o próximo lote, sem necessariamente depender de contar desde o início a cada vez.

Essa abordagem pode funcionar melhor para listas que mudam com frequência, mas o cursor deve ser projetado com uma ordem estável e atributos apropriados. Não é uma chave mágica que resolve qualquer problema de consistência.

O que uma boa API deveria devolver?

Além dos itens, pode incluir um indicador de continuação e links ou parâmetros para solicitar o próximo conjunto. Às vezes é útil informar o total de registros, mas calculá-lo também pode ter custos.

O importante é documentar claramente as regras: limite máximo de página, ordem aplicada, filtros admitidos e comportamento se o cursor expirar ou for inválido.

O cliente não deveria poder solicitar arbitrariamente vinte milhões de registros se essa operação puder afetar todos os outros usuários.

A ordem é indispensável

Imagine consultar primeiro os vinte pedidos mais recentes. Se você não definir explicitamente como ordená-los, o mecanismo de banco de dados não promete devolver sempre uma sequência lógica. A paginação sem ordem estável pode produzir resultados confusos.

É útil ordenar por uma data e resolver empates com um identificador único. A estratégia exata depende do mecanismo e de como os registros são inseridos.

E como se compara com uma busca?

Buscar e paginar são problemas distintos. Uma busca decide quais registros correspondem aos filtros; a paginação decide quantos são entregues e como continuar.

Se o usuário alterar os filtros, normalmente ele deve reiniciar o percurso. Reutilizar o cursor anterior com outra consulta pode gerar resultados incorretos.

Três erros que aparecem em produção

Permitir limites enormes: uma única solicitação pode consumir muita memória ou tempo de processamento.

Omitir a ordenação: as páginas deixam de ter um significado consistente.

Inventar um total exato sem medir: em bancos grandes, calcular o número exato pode ser mais caro do que devolver a página solicitada.

Para APIs sensíveis, também é necessário verificar a autorização: paginar não deve permitir obter registros de outras pessoas.

Onde entra o ArduMaker?

Se você publicar um backend em um VPS da ArduMaker, a paginação ajuda a reduzir a carga de suas consultas e o volume de dados transferidos. O painel pode facilitar a implantação, mas o comportamento da API e seu banco de dados corresponde ao projeto.

Em resumo: paginar não é dividir uma tela visual em páginas. É projetar como recuperar grandes conjuntos de dados de forma eficiente, previsível e segura.

Fontes: Guia de design de APIs da Microsoft · LIMIT e OFFSET no PostgreSQL.