Como paginar uma API REST em Python (requests)

Quando pedes dados a uma API REST, raramente recebes tudo de uma só vez: para poupar recursos, a maioria das APIs divide os resultados em páginas. Se leres apenas a primeira, ficas com dados incompletos. A boa notícia é que paginar uma API REST em Python é simples com a biblioteca requests — basta um ciclo que percorre todas as páginas e vai juntando os resultados. Vamos ver como, com exemplos práticos.

Pré-requisitos

• Python 3.9 ou superior instalado.
• A biblioteca requests instalada (pip install requests).
• Uma API REST que devolva dados em páginas e o acesso à sua documentação.
• Conhecimentos básicos de Python (dicionários e ciclos while).

Passo 1: Fazer o primeiro pedido à API

Antes de pensar em páginas, garante que consegues obter uma. Com requests.get fazes um pedido e, com raise_for_status, garantes que qualquer erro de rede ou de autenticação é sinalizado logo em vez de passar despercebido. O timeout evita que o teu programa fique preso à espera para sempre.

import requests

BASE_URL = "https://api.example.com/items"

resposta = requests.get(BASE_URL, params={"page": 1}, timeout=10)
resposta.raise_for_status()
dados = resposta.json()
print(dados)

Substitui BASE_URL pelo endpoint real da tua API. Ao imprimir a resposta consegues ver a estrutura dos dados — normalmente um dicionário com uma lista de registos lá dentro.

Passo 2: Perceber como a API pagina

Existem dois estilos de paginação muito comuns, e precisas de saber qual a tua API usa (a documentação diz-te). No primeiro, indicas o número da página num parâmetro como ?page=2. No segundo, cada resposta traz o endereço da página seguinte num campo, muitas vezes chamado next. APIs criadas com Django REST Framework, por exemplo, devolvem os campos results, next e count — a estrutura que vamos usar nos exemplos.

Dica: antes de escrever o ciclo, lê a documentação da API para saber o nome do parâmetro da página, o tamanho máximo por página e o limite de pedidos por minuto.

Passo 3: Percorrer todas as páginas por número

A ideia é simples: começas na página 1 e vais pedindo a página seguinte até a API devolver uma lista vazia, sinal de que já não há mais dados. Um contador e um ciclo while chegam para isso.

todos = []
pagina = 1

while True:
    resposta = requests.get(BASE_URL, params={"page": pagina}, timeout=10)
    resposta.raise_for_status()
    lote = resposta.json()["results"]
    if not lote:
        break
    todos.extend(lote)
    pagina += 1

print(f"Total de registos: {len(todos)}")

A cada volta do ciclo pedimos uma página, acrescentamos os seus registos à lista todos com extend e avançamos o contador. Quando lote vem vazio, o break termina o ciclo.

Passo 4: Seguir o campo "next" (paginação por cursor)

Se a tua API devolve o endereço da página seguinte, nem precisas de contar páginas: segues o campo next até ele ficar vazio. Este método é ainda mais robusto, porque é a própria API a dizer-te qual o passo seguinte.

todos = []
url = BASE_URL

while url:
    resposta = requests.get(url, timeout=10)
    resposta.raise_for_status()
    dados = resposta.json()
    todos.extend(dados["results"])
    url = dados.get("next")

print(f"Total de registos: {len(todos)}")

Enquanto houver um next, o ciclo continua. Quando a última página traz next a null, o get devolve None, a condição do while passa a falsa e o ciclo termina naturalmente.

Passo 5: Evitar erros e respeitar a API

Percorrer muitas páginas depressa pode fazer a API bloquear-te por excesso de pedidos (o famoso erro 429 Too Many Requests). Uma pausa curta entre pedidos e um limite de segurança tornam o teu código mais educado e mais seguro contra ciclos infinitos.

import time

todos = []
pagina = 1
MAX_PAGINAS = 500

while pagina <= MAX_PAGINAS:
    resposta = requests.get(BASE_URL, params={"page": pagina}, timeout=10)
    resposta.raise_for_status()
    lote = resposta.json()["results"]
    if not lote:
        break
    todos.extend(lote)
    pagina += 1
    time.sleep(0.2)

print(f"Total de registos: {len(todos)}")

Verificar o resultado

Como sabes que apanhaste mesmo todos os registos? Muitas APIs incluem um campo com o total, como count. Basta comparar esse número com o tamanho da tua lista:

print(len(todos))
print(dados["count"])

Se os dois valores coincidirem, a paginação percorreu tudo. Em alternativa, confirma que a última página devolveu menos registos do que o tamanho normal de página — sinal de que chegaste ao fim.

Conclusão

Já sabes paginar uma API REST em Python nos dois formatos mais comuns — por número de página e por campo next — e ainda proteger o teu código com pausas e limites. O próximo passo natural é guardar os dados de todos num DataFrame do pandas ou numa base de dados para análise. Qual das tuas APIs vais paginar primeiro?