Paginação da API REST do GitHub e leitura dos cabeçalhos de limite de taxa primário e secundário

O que é

O guia de paginação do GitHub mostra um cabeçalho de resposta link como <...?page=2>; rel="prev", <...?page=4>; rel="next", <...?page=515>; rel="last" e orienta os clientes a usar essas URLs diretamente, em vez de montar eles mesmos as URLs das páginas: "The URL for the next page is followed by rel="next"." Dependendo do endpoint, essas URLs usam page, before/after ou since. A documentação do GitHub observa que "for most endpoints, the maximum value of per_page is 100," e um valor maior é reduzido silenciosamente, sem ser rejeitado. Os limites de taxa primários são informados em todas as respostas por meio de x-ratelimit-limit, x-ratelimit-remaining, x-ratelimit-used, x-ratelimit-reset (segundos de época UTC) e x-ratelimit-resource (o bucket em que a requisição foi contabilizada). Além disso, o GitHub aplica limites de taxa secundários; entre os tetos documentados estão no máximo 100 requisições simultâneas, 900 pontos por minuto para endpoints da API REST, 90 segundos de tempo de CPU a cada 60 segundos de tempo real e no máximo 80 requisições de geração de conteúdo por minuto (500 por hora). Exceder qualquer um dos dois tipos retorna 403 ou 429; uma resposta de limite secundário pode trazer retry-after e, quando não traz, o GitHub orienta a esperar até x-ratelimit-reset se x-ratelimit-remaining for 0, "otherwise, wait for at least one minute before retrying", com espera exponencialmente crescente em caso de repetição. A página de boas práticas do GitHub acrescenta que uma requisição condicional "does not count against your primary rate limit if a 304 response is returned and the request was made while correctly authorized with an Authorization header."

Por que importa

Montar URLs de página à mão quebra sempre que o GitHub altera os parâmetros de consulta (isso já difere entre endpoints que usam números de página e endpoints que usam cursores). Ignorar o cabeçalho retry-after do limite secundário, mesmo com saldo saudável no limite primário, é uma forma comum de ser bloqueado temporariamente apesar de ainda haver cota primária disponível.

Como aplicar

• Siga literalmente a URL rel="next" do cabeçalho link; pare quando não houver relação next.
• Solicite per_page=100 em tarefas com muita leitura para reduzir o número de idas e vindas, e nunca presuma que um valor maior solicitado foi aceito.
• Acompanhe x-ratelimit-remaining e x-ratelimit-reset; reduza o ritmo bem antes de o remaining chegar a zero, em vez de reagir só a um 403/429.
• Em qualquer resposta com retry-after, espere pelo menos esse número de segundos, independentemente da folga no limite primário; em um erro de limite secundário sem esse cabeçalho, espere pelo menos um minuto.
• Envie requisições de escrita em série e com pelo menos um segundo de intervalo, como o GitHub recomenda para evitar os limites secundários.
• Em cargas de trabalho de polling, envie If-None-Match com um ETag armazenado; um 304 autorizado não consome o limite primário.

import requests

def get_all_pages(url, headers):
    items = []
    while url:
        r = requests.get(url, headers=headers)
        r.raise_for_status()
        items += r.json()
        url = r.links.get("next", {}).get("url")
    return items

Armadilhas

Paginar com números page= montados à mão a partir de per_page, o que falha em endpoints que só oferecem paginação por cursor. Tratar o cabeçalho retry-after como opcional porque o x-ratelimit-remaining primário ainda mostra folga. Presumir que todo erro de limite de taxa é um 429: o GitHub também usa 403, então verifique os cabeçalhos e a mensagem de erro antes de tratar um 403 como problema de permissão.