Como Implementar Paginação em APIs REST: Guia Passo a Passo

Ao construir APIs REST que retornam uma lista de recursos, é crucial considerar como lidar com grandes conjuntos de dados. Retornar milhares ou até milhões de registros em uma única resposta de API é impraticável e pode levar a problemas significativos de desempenho, alto consumo de memória tanto para o servidor quanto para o cliente, e uma experiência de usuário ruim. A paginação é a solução padrão para este problema. Ela envolve a divisão de um grande conjunto de dados em partes menores e gerenciáveis, chamadas "páginas", que são então servidas sequencialmente. Este tutorial irá guiá-lo pelos passos técnicos da implementação de várias estratégias de paginação em suas APIs REST.

💡

Quer uma ótima ferramenta de Teste de API que gera documentação de API bonita?

Quer uma plataforma integrada e All-in-One para sua Equipe de Desenvolvedores trabalharem juntos com máxima produtividade?

Apidog entrega todas as suas demandas, e substitui o Postman por um preço muito mais acessível!

button

Por que a Paginação é Essencial?

Antes de mergulhar nos detalhes de implementação, vamos abordar brevemente por que a paginação é um recurso inegociável para APIs que lidam com coleções de recursos:

Desempenho: Solicitar e transferir grandes quantidades de dados pode ser lento. A paginação reduz o tamanho do payload de cada requisição, levando a tempos de resposta mais rápidos e menor carga no servidor.
Consumo de Recursos: Respostas menores consomem menos memória no servidor que as gera e no cliente que as processa. Isso é especialmente crítico para clientes móveis ou ambientes com recursos limitados.
Limite de Taxa (Rate Limiting) e Cotas: Muitas APIs impõem limites de taxa. A paginação ajuda os clientes a permanecerem dentro desses limites buscando dados em partes menores ao longo do tempo, em vez de tentar obter tudo de uma vez.
Experiência do Usuário: Para interfaces de usuário que consomem a API, apresentar dados em páginas é muito mais amigável do que sobrecarregar os usuários com uma lista enorme ou uma rolagem muito longa.
Eficiência do Banco de Dados: Buscar um subconjunto de dados é geralmente menos custoso para o banco de dados em comparação com a recuperação de uma tabela inteira, especialmente se a indexação adequada estiver em vigor.

Estratégias Comuns de Paginação

Existem várias estratégias comuns para implementar paginação, cada uma com seus próprios trade-offs. Exploraremos as mais populares: offset/limit (frequentemente referida como paginação baseada em página) e baseada em cursor (também conhecida como keyset ou seek pagination).

1. Paginação Offset/Limit (ou Baseada em Página)

Esta é, sem dúvida, o método de paginação mais direto e amplamente adotado. Funciona permitindo que o cliente especifique dois parâmetros principais:

offset: O número de registros a serem pulados desde o início do conjunto de dados.
limit: O número máximo de registros a serem retornados em uma única página.

Alternativamente, os clientes podem especificar:

page: O número da página que desejam recuperar.
pageSize (ou per_page, limit): O número de registros por página.

O offset pode ser calculado a partir de page e pageSize usando a fórmula: offset = (page - 1) * pageSize.

Passos Técnicos de Implementação:

Vamos supor que temos um endpoint de API /items que retorna uma lista de itens.

a. Parâmetros da Requisição API:
O cliente faria uma requisição como:
GET /items?offset=20&limit=10 (buscar 10 itens, pulando os primeiros 20)
ou
GET /items?page=3&pageSize=10 (buscar a 3ª página, com 10 itens por página, o que é equivalente a offset=20, limit=10).

É uma boa prática definir valores padrão para esses parâmetros (por exemplo, limit=20, offset=0 ou page=1, pageSize=20) se o cliente não os fornecer. Além disso, imponha um limit ou pageSize máximo para evitar que os clientes solicitem um número excessivamente grande de registros, o que poderia sobrecarregar o servidor.

b. Lógica de Backend (Conceitual):
Quando o servidor recebe esta requisição, ele precisa traduzir esses parâmetros em uma consulta ao banco de dados.

// Exemplo em Java com Spring Boot
@GetMapping("/items")
public ResponseEntity<PaginatedResponse<Item>> getItems(
    @RequestParam(defaultValue = "0") int offset,
    @RequestParam(defaultValue = "20") int limit
) {
    // Validar limite para prevenir abuso
    if (limit > 100) {
        limit = 100; // Impor um limite máximo
    }

    List<Item> items = itemRepository.findItemsWithOffsetLimit(offset, limit);
    long totalItems = itemRepository.countTotalItems(); // Para metadados

    // Construir e retornar resposta paginada
    // ...
}

c. Consulta ao Banco de Dados (Exemplo SQL):
A maioria dos bancos de dados relacionais suporta cláusulas offset e limit diretamente.

Para PostgreSQL ou MySQL:

SELECT *
FROM items
ORDER BY created_at DESC -- Ordenação consistente é crucial para paginação estável
LIMIT 10 -- Este é o parâmetro 'limit'
OFFSET 20; -- Este é o parâmetro 'offset'

Para SQL Server (versões mais antigas podem usar ROW_NUMBER()):

SELECT *
FROM items
ORDER BY created_at DESC
OFFSET 20 ROWS
FETCH NEXT 10 ROWS ONLY;

Para Oracle:

SELECT *
FROM (
    SELECT i.*, ROWNUM rnum
    FROM (
        SELECT *
        FROM items
        ORDER BY created_at DESC
    ) i
    WHERE ROWNUM <= 20 + 10 -- offset + limit
)
WHERE rnum > 20; -- offset

Nota Importante sobre Ordenação: Para que a paginação offset/limit seja confiável, o conjunto de dados subjacente deve ser ordenado por uma chave consistente e única (ou quase única), ou uma combinação de chaves. Se a ordem dos itens puder mudar entre as requisições (por exemplo, novos itens sendo inseridos ou itens sendo atualizados de forma que afete sua ordem de classificação), os usuários podem ver itens duplicados ou perder itens ao navegar pelas páginas. Uma escolha comum é ordenar por timestamp de criação ou por um ID primário.

d. Estrutura da Resposta da API:
Uma boa resposta paginada deve incluir não apenas os dados da página atual, mas também metadados para ajudar o cliente a navegar.

{
  "data": [
    // array de itens para a página atual
    { "id": "item_21", "name": "Item 21", ... },
    { "id": "item_22", "name": "Item 22", ... },
    // ... até 'limit' itens
    { "id": "item_30", "name": "Item 30", ... }
  ],
  "pagination": {
    "offset": 20,
    "limit": 10,
    "totalItems": 5000, // Número total de itens disponíveis
    "totalPages": 500, // Calculado como ceil(totalItems / limit)
    "currentPage": 3 // Calculado como (offset / limit) + 1
  },
  "links": { // Links HATEOAS para navegação
    "self": "/items?offset=20&limit=10",
    "first": "/items?offset=0&limit=10",
    "prev": "/items?offset=10&limit=10", // Nulo se estiver na primeira página
    "next": "/items?offset=30&limit=10", // Nulo se estiver na última página
    "last": "/items?offset=4990&limit=10"
  }
}

Fornecer links HATEOAS (Hypermedia as the Engine of Application State) (self, first, prev, next, last) é uma boa prática REST. Isso permite que os clientes naveguem pelas páginas sem ter que construir as URLs eles mesmos.

Prós da Paginação Offset/Limit:

Simplicidade: Fácil de entender e implementar.
Navegação com Estado: Permite navegação direta para qualquer página específica (por exemplo, "ir para a página 50").
Amplamente Suportado: O suporte a OFFSET e LIMIT em bancos de dados é comum.

Contras da Paginação Offset/Limit:

Degradação de Desempenho com Grandes Offsets: Conforme o valor do offset aumenta, os bancos de dados podem ficar mais lentos. O banco de dados frequentemente ainda precisa escanear todas as linhas offset + limit antes de descartar as offset linhas. Isso pode ser ineficiente para páginas profundas.
Desvio de Dados/Itens Perdidos: Se novos itens forem adicionados ou itens existentes forem removidos do conjunto de dados enquanto um usuário está paginando, a "janela" de dados pode mudar. Isso pode fazer com que um usuário veja o mesmo item em duas páginas diferentes ou perca um item completamente. Isso é particularmente problemático com conjuntos de dados frequentemente atualizados. Por exemplo, se você estiver na página 2 (itens 11-20) e um novo item for adicionado no início da lista, ao solicitar a página 3, o que antes era o item 21 agora é o item 22. Você pode perder o novo item 21 ou ver duplicatas dependendo do momento exato e dos padrões de exclusão.

2. Paginação Baseada em Cursor (Keyset/Seek)

A paginação baseada em cursor aborda algumas das deficiências do offset/limit, particularmente o desempenho com grandes conjuntos de dados e problemas de consistência de dados. Em vez de depender de um offset absoluto, ela usa um "cursor" que aponta para um item específico no conjunto de dados. O cliente então solicita itens "depois" ou "antes" deste cursor.

O cursor é tipicamente uma string opaca que codifica o(s) valor(es) da(s) chave(s) de ordenação do último item recuperado na página anterior.

Passos Técnicos de Implementação:

a. Parâmetros da Requisição API:
O cliente faria uma requisição como:
GET /items?limit=10 (para a primeira página)
E para páginas subsequentes:
GET /items?limit=10&after_cursor=stringopaquarepresentandoidoultimoitem
Ou, para paginar para trás (menos comum, mas possível):
GET /items?limit=10&before_cursor=stringopaquarepresentandoidprimeiroitem

O parâmetro limit ainda define o tamanho da página.

b. O que é um Cursor?
Um cursor deve ser:

Opaco para o cliente: O cliente não deve precisar entender sua estrutura interna. Ele apenas o recebe de uma resposta e o envia de volta na próxima requisição.
Baseado em coluna(s) única(s) e sequencialmente ordenada(s): Tipicamente, este é o ID primário (se for sequencial como um UUIDv1 ou uma sequência de banco de dados) ou uma coluna de timestamp. Se uma única coluna não for única o suficiente (por exemplo, vários itens podem ter o mesmo timestamp), uma combinação de colunas é usada (por exemplo, timestamp + id).
Codificável e Decodificável: Frequentemente codificado em Base64 para garantir que seja seguro para URL. Poderia ser tão simples quanto o próprio ID, ou um objeto JSON { "last_id": 123, "last_timestamp": "2023-10-27T10:00:00Z" } que é então codificado em Base64.

c. Lógica de Backend (Conceitual):

// Exemplo em Java com Spring Boot
@GetMapping("/items")
public ResponseEntity<CursorPaginatedResponse<Item>> getItems(
    @RequestParam(defaultValue = "20") int limit,
    @RequestParam(required = false) String afterCursor
) {
    // Validar limite
    if (limit > 100) {
        limit = 100;
    }

    // Decodificar cursor para obter as propriedades do último item visto
    // e.g., LastSeenItemDetails lastSeen = decodeCursor(afterCursor);
    // Se afterCursor for nulo, é a primeira página.

    List<Item> items;
    if (afterCursor != null) {
        DecodedCursor decoded = decodeCursor(afterCursor); // e.g., { lastId: "some_uuid", lastCreatedAt: "timestamp" }
        items = itemRepository.findItemsAfter(decoded.getLastCreatedAt(), decoded.getLastId(), limit);
    } else {
        items = itemRepository.findFirstPage(limit);
    }

    String nextCursor = null;
    if (!items.isEmpty() && items.size() == limit) {
        // Assumindo que os itens estão ordenados, o último item da lista é usado para gerar o próximo cursor
        Item lastItemOnPage = items.get(items.size() - 1);
        nextCursor = encodeCursor(lastItemOnPage.getCreatedAt(), lastItemOnPage.getId());
    }

    // Construir e retornar resposta paginada baseada em cursor
    // ...
}

// Métodos auxiliares para codificar/decodificar cursores
// private DecodedCursor decodeCursor(String cursor) { ... }
// private String encodeCursor(Timestamp createdAt, String id) { ... }

d. Consulta ao Banco de Dados (Exemplo SQL):
A chave é usar uma cláusula WHERE que filtra registros com base na(s) chave(s) de ordenação do cursor. A cláusula ORDER BY deve estar alinhada com a composição do cursor.

Assumindo ordenação por created_at (descendente) e depois por id (descendente) como desempate para ordenação estável se created_at não for único:

Para a primeira página:

SELECT *
FROM items
ORDER BY created_at DESC, id DESC
LIMIT 10;

Para páginas subsequentes, se o cursor decodificado for last_created_at_from_cursor e last_id_from_cursor:

SELECT *
FROM items
WHERE (created_at, id) < (CAST('last_created_at_from_cursor' AS TIMESTAMP), CAST('last_id_from_cursor' AS UUID)) -- Ou tipos apropriados
-- Para ordem ascendente, seria >
-- A comparação de tupla (created_at, id) < (val1, val2) é uma forma concisa de escrever:
-- WHERE created_at < 'last_created_at_from_cursor'
--    OR (created_at = 'last_created_at_from_cursor' AND id < 'last_id_from_cursor')
ORDER BY created_at DESC, id DESC
LIMIT 10;

Este tipo de consulta é muito eficiente, especialmente se houver um índice em (created_at, id). O banco de dados pode "buscar" diretamente o ponto de partida sem escanear linhas irrelevantes.

e. Estrutura da Resposta da API:

{
  "data": [
    // array de itens para a página atual
    { "id": "item_N", "createdAt": "2023-10-27T10:05:00Z", ... },
    // ... até 'limit' itens
    { "id": "item_M", "createdAt": "2023-10-27T10:00:00Z", ... }
  ],
  "pagination": {
    "limit": 10,
    "hasNextPage": true, // booleano indicando se há mais dados
    "nextCursor": "stringopaquacodificadaembase64paraitem_M" // string opaca
    // Potencialmente um "prevCursor" se cursores bidirecionais forem suportados
  },
  "links": {
    "self": "/items?limit=10&after_cursor=cursor_da_requisicao_atual_se_houver",
    "next": "/items?limit=10&after_cursor=stringopaquacodificadaembase64paraitem_M" // Nulo se não houver próxima página
  }
}

Observe que a paginação baseada em cursor tipicamente não fornece totalPages ou totalItems porque calcular estes exigiria um scan completo da tabela, negando alguns dos benefícios de desempenho. Se estes forem estritamente necessários, um endpoint separado ou uma estimativa podem ser fornecidos.

Prós da Paginação Baseada em Cursor:

Desempenho em Grandes Conjuntos de Dados: Geralmente tem melhor desempenho do que offset/limit para paginação profunda, pois o banco de dados pode buscar eficientemente a posição do cursor usando índices.
Estável em Conjuntos de Dados Dinâmicos: Menos suscetível a itens perdidos ou duplicados quando dados são frequentemente adicionados ou removidos, pois o cursor se ancora a um item específico. Se um item antes do cursor for excluído, isso não afeta os itens subsequentes.
Adequado para Rolagem Infinita: O modelo de "próxima página" se encaixa naturalmente com interfaces de rolagem infinita.

Contras da Paginação Baseada em Cursor:

Sem "Ir para a Página": Os usuários não podem navegar diretamente para um número de página arbitrário (por exemplo, "página 5"). A navegação é estritamente sequencial (próxima/anterior).
Implementação Mais Complexa: Definir e gerenciar cursores, especialmente com múltiplas colunas de ordenação ou ordens de classificação complexas, pode ser mais intrincado.
Limitações de Ordenação: A ordem de classificação deve ser fixa e baseada nas colunas usadas para o cursor. Mudar a ordem de classificação dinamicamente com cursores é complexo.

Escolhendo a Estratégia Certa

A escolha entre paginação offset/limit e baseada em cursor depende dos seus requisitos específicos:

Offset/Limit é frequentemente suficiente se:
O conjunto de dados for relativamente pequeno ou não mudar com frequência.
A capacidade de pular para páginas arbitrárias for um recurso crítico.
A simplicidade de implementação for uma alta prioridade.
O desempenho para páginas muito profundas não for uma grande preocupação.
Baseada em Cursor é geralmente preferida se:
Você estiver lidando com conjuntos de dados muito grandes e que mudam frequentemente.
O desempenho em escala e a consistência dos dados durante a paginação forem primordiais.
A navegação sequencial (como rolagem infinita) for o caso de uso principal.
Você não precisar exibir o número total de páginas ou permitir pular para páginas específicas.

Em alguns sistemas, uma abordagem híbrida é até usada, ou diferentes estratégias são oferecidas para diferentes casos de uso ou endpoints.

Melhores Práticas para Implementar Paginação

Independentemente da estratégia escolhida, adira a estas melhores práticas:

Nomenclatura Consistente de Parâmetros: Use nomes claros e consistentes para seus parâmetros de paginação (por exemplo, limit, offset, page, pageSize, after_cursor, before_cursor). Mantenha uma convenção (por exemplo, camelCase ou snake_case) em toda a sua API.
Forneça Links de Navegação (HATEOAS): Conforme mostrado nos exemplos de resposta, inclua links para self, next, prev, first e last (onde aplicável). Isso torna a API mais descobrível e desacopla o cliente da lógica de construção de URL.
Valores Padrão e Limites Máximos:

Sempre defina valores padrão sensatos para limit (por exemplo, 10 ou 25).
Imponha um limit máximo para evitar que os clientes solicitem muitos dados e sobrecarreguem o servidor (por exemplo, máximo de 100 registros por página). Retorne um erro ou limite o valor se um valor inválido for solicitado.

Documentação Clara da API: Documente sua estratégia de paginação completamente:

Explique os parâmetros usados.
Forneça exemplos de requisições e respostas.
Esclareça os limites padrão e máximos.
Explique como os cursores são usados (se aplicável), sem revelar sua estrutura interna se forem destinados a ser opacos.

Ordenação Consistente: Garanta que os dados subjacentes sejam ordenados consistentemente para cada requisição paginada. Para offset/limit, isso é vital para evitar desvio de dados. Para baseada em cursor, a ordem de classificação dita como os cursores são construídos e interpretados. Use uma coluna de desempate única (como um ID primário) se a coluna de classificação primária puder ter valores duplicados.
Lide com Casos Limite:

Resultados Vazios: Retorne um array de dados vazio e metadados de paginação apropriados (por exemplo, totalItems: 0 ou hasNextPage: false).
Parâmetros Inválidos: Retorne um erro 400 Bad Request se os clientes fornecerem parâmetros de paginação inválidos (por exemplo, limite negativo, número de página não inteiro).
Cursor Não Encontrado (para baseada em cursor): Se um cursor fornecido for inválido ou apontar para um item excluído, decida um comportamento: retorne um 404 Not Found ou 400 Bad Request, ou volte graciosamente para a primeira página.

Considerações sobre Contagem Total:

Para offset/limit, fornecer totalItems e totalPages é comum. Esteja ciente de que COUNT(*) pode ser lento em tabelas muito grandes. Explore otimizações específicas do banco de dados ou estimativas se isso se tornar um gargalo.
Para baseada em cursor, totalItems é frequentemente omitido por desempenho. Se necessário, considere fornecer uma contagem estimada ou um endpoint separado que a calcule (potencialmente de forma assíncrona).

Tratamento de Erros: Retorne códigos de status HTTP apropriados para erros (por exemplo, 400 para entrada inválida, 500 para erros do servidor durante a busca de dados).
Segurança: Embora não seja diretamente um mecanismo de paginação, garanta que os dados sendo paginados respeitem as regras de autorização. Um usuário só deve poder paginar dados que ele tem permissão para ver.
Cache: Respostas paginadas frequentemente podem ser cacheadas. Para paginação baseada em offset, GET /items?page=2&pageSize=10 é altamente cacheável. Para baseada em cursor, GET /items?limit=10&after_cursor=XYZ também é cacheável. Garanta que sua estratégia de cache funcione bem com a forma como os links de paginação são gerados e consumidos. Estratégias de invalidação precisam ser consideradas se os dados subjacentes mudarem frequentemente.

Tópicos Avançados (Menções Breves)

Rolagem Infinita: A paginação baseada em cursor é um ajuste natural para interfaces de rolagem infinita. O cliente busca a primeira página e, conforme o usuário rola perto do final, usa o nextCursor para buscar o conjunto subsequente de itens.
Paginação com Filtragem e Ordenação Complexas: Ao combinar paginação com parâmetros dinâmicos de filtragem e ordenação, garanta que:
Para offset/limit: A contagem de totalItems reflita precisamente o conjunto de dados filtrado.
Para baseada em cursor: O cursor codifique o estado tanto da ordenação quanto da filtragem, se estas afetarem o que "próximo" significa. Isso pode complicar significativamente o design do cursor. Frequentemente, se os filtros ou a ordem de classificação mudarem, a paginação é redefinida para a "primeira página" da nova visualização.
Paginação GraphQL: GraphQL tem sua própria maneira padronizada de lidar com paginação, frequentemente referida como "Connections". Ela tipicamente usa paginação baseada em cursor e tem uma estrutura definida para retornar edges (itens com cursores) e informações da página. Se você estiver usando GraphQL, adira às suas convenções (por exemplo, especificação Relay Cursor Connections).

Conclusão

Implementar a paginação corretamente é fundamental para construir APIs REST escaláveis e amigáveis ao usuário. Embora a paginação offset/limit seja mais simples para começar, a paginação baseada em cursor oferece desempenho e consistência superiores para conjuntos de dados grandes e dinâmicos. Ao entender os detalhes técnicos de cada estratégia, escolher aquela que melhor se adapta às necessidades da sua aplicação e seguir as melhores práticas de implementação e design de API, você pode garantir que sua API entregue dados eficientemente aos seus clientes, independentemente da escala. Lembre-se de sempre priorizar documentação clara e tratamento robusto de erros para fornecer uma experiência suave aos consumidores da API.