Paginacao API: como implementar passo a passo

Paginacao em APIs REST e a forma de entregar grandes conjuntos de dados em blocos menores, evitando respostas pesadas e lentidao. Em vez de retornar milhares de registros de uma vez, a API devolve uma pagina por requisicao. Este guia mostra o passo a passo para implementar, com exemplos praticos e erros comuns a evitar.

Passo 1: Escolha a estrategia de paginacao

A decisao mais importante vem antes do codigo. As duas abordagens mais usadas sao:

• Offset (pagina e limite): o cliente envia page e limit (ou offset e limit). Simples de implementar, mas fica lento em tabelas muito grandes, pois o banco precisa percorrer todos os registros anteriores.
• Cursor (baseado em chave): o cliente recebe um cursor que aponta para a posicao exata do ultimo item. Mais eficiente para grandes volumes, pois nao depende do numero de paginas.

Para a maioria das APIs com poucos milhares de registros, offset resolve bem. Para dados em constante crescimento, cursor e mais seguro. Exemplo de resposta com offset:

{ "data": [...], "page": 1, "limit": 20, "total": 157 }

Erro comum: usar offset sem limite maximo. Se o cliente pedir limit=10000, a API pode travar. Defina um teto, como 100 ou 200 itens por pagina.

Passo 2: Defina os parametros de entrada e saida

Padronize os nomes dos parametros. Os mais comuns sao page (comecando em 1), limit (quantidade por pagina) e total (numero total de registros). Para cursor, use cursor e next_cursor na resposta.

Exemplo de requisicao com offset:

GET /api/produtos?page=2&limit=20

E a resposta deve incluir metadados que ajudem o cliente a navegar:

{ "data": [...], "pagination": { "page": 2, "limit": 20, "total": 157, "total_pages": 8 } }

Dica: inclua sempre next_page ou next_cursor para o cliente saber se ha mais dados. Isso evita que ele fique adivinhando.

Passo 3: Implemente a consulta no banco de dados

No backend, traduza os parametros para a consulta. Em SQL, com offset, seria algo como:

SELECT * FROM produtos ORDER BY id LIMIT 20 OFFSET 40;

O OFFSET e calculado como (page - 1) * limit. No caso acima, pagina 3 com limite 20 comeca no registro 41.

Para cursor, a consulta usa uma condicao de comparacao:

SELECT * FROM produtos WHERE id > ? ORDER BY id LIMIT 20;

O valor de ? e o cursor recebido. Isso elimina o custo de pular registros.

Erro comum: esquecer de usar ORDER BY em campo unico. Sem uma ordem estavel, os resultados podem se repetir ou pular itens entre paginas.

Passo 4: Trate os limites e erros

Valide os parametros antes de executar a consulta. Se page for menor que 1, retorne erro 400. Se limit exceder o valor maximo permitido, ajuste para o teto ou devolva um aviso.

Exemplo de resposta de erro:

{ "error": "limit deve ser entre 1 e 100" }

Dica: use o codigo HTTP correto. 400 para requisicao invalida, 404 para pagina inexistente, 200 para sucesso.

Passo 5: Documente e teste

Documente os parametros de paginacao na sua API, com exemplos de requisicao e resposta. Teste os casos limite: pagina vazia, ultima pagina, limite maximo e ordenacao.

Erro comum: nao testar com dados reais. Uma tabela com 10 registros nao revela problemas de performance que aparecem com 1 milhao.

Checklist final

• [ ] Estrategia escolhida (offset ou cursor) adequada ao volume de dados.
• [ ] Parametros padronizados e documentados.
• [ ] Limite maximo definido e validado.
• [ ] Ordenacao estavel em campo unico.
• [ ] Metadados de paginacao na resposta (total, next_page ou next_cursor).
• [ ] Testes de borda realizados.

Perguntas frequentes sobre paginacao em APIs

Qual a diferenca entre offset e cursor?

Offset usa numero de pagina e quantidade por pagina, simples de implementar, mas ineficiente em grandes volumes. Cursor usa um identificador do ultimo item, mais rapido, porem exige que a ordenacao seja estavel e que o campo do cursor seja unico.

Como calcular o total de paginas?

Divida o total de registros pelo limite e arredonde para cima. Exemplo: 157 registros com limite 20 resultam em 8 paginas (157 / 20 = 7,85, arredondado para 8).

Posso usar paginacao por cursor em qualquer banco?

Sim, desde que o campo usado como cursor (como id) seja unico e indexado. Em bancos relacionais, use WHERE id > cursor ORDER BY id. Em NoSQL, a logica e similar com a chave de particao.

O que acontece se o cliente pedir uma pagina alem da ultima?

O ideal e retornar uma lista vazia com status 200, indicando que nao ha mais dados. Alguns preferem 404, mas isso pode confundir o cliente. O importante e documentar o comportamento.

Como evitar que a paginacao fique lenta com muitos dados?

Prefira cursor em vez de offset, adicione indices no campo de ordenacao e defina um limite maximo de itens por pagina. Para dados muito grandes, considere paginacao baseada em chave com particionamento.