Paginación de la API REST de GitHub y lectura de sus cabeceras de límite de tasa primario y secundario

Qué es

La guía de paginación de GitHub muestra una cabecera de respuesta link como <...?page=2>; rel="prev", <...?page=4>; rel="next", <...?page=515>; rel="last" e indica a los clientes que usen esas URL tal cual, en lugar de construir ellos mismos las URL de las páginas: "The URL for the next page is followed by rel="next"." Según el endpoint, esas URL usan page, before/after o since. La documentación de GitHub señala que "for most endpoints, the maximum value of per_page is 100," y que un valor mayor se reduce sin avisar en lugar de rechazarse. Los límites de tasa primarios se informan en cada respuesta mediante x-ratelimit-limit, x-ratelimit-remaining, x-ratelimit-used, x-ratelimit-reset (segundos epoch en UTC) y x-ratelimit-resource (el bucket al que se imputó la solicitud). Por separado, GitHub aplica límites de tasa secundarios; entre los topes documentados están un máximo de 100 solicitudes concurrentes, 900 puntos por minuto para los endpoints de la API REST, 90 segundos de tiempo de CPU por cada 60 segundos de tiempo real y un máximo de 80 solicitudes que generan contenido por minuto (500 por hora). Superar cualquiera de los dos tipos de límite devuelve 403 o 429; una respuesta por límite secundario puede incluir retry-after y, si no lo incluye, GitHub indica esperar hasta x-ratelimit-reset cuando x-ratelimit-remaining es 0; "otherwise, wait for at least one minute before retrying", con espera exponencial creciente si se repite. La página de buenas prácticas de GitHub añade que una solicitud 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 qué importa

Construir a mano las URL de las páginas deja de funcionar cada vez que GitHub cambia los parámetros de consulta (ya hoy difieren entre los endpoints que usan números de página y los que usan cursores). Ignorar la cabecera retry-after del límite secundario, aunque el saldo del límite primario esté sano, es una forma habitual de sufrir un bloqueo temporal con cuota primaria todavía disponible.

Cómo aplicarlo

• Sigue literalmente la URL rel="next" de la cabecera link; detente cuando no haya ninguna relación next.
• Solicita per_page=100 en los trabajos con muchas lecturas para minimizar los viajes de ida y vuelta, y no des por hecho que se haya respetado un valor mayor.
• Vigila x-ratelimit-remaining y x-ratelimit-reset; reduce el ritmo con bastante antelación, antes de que remaining llegue a cero, en lugar de reaccionar solo ante un 403/429.
• Ante cualquier respuesta con retry-after, espera al menos ese número de segundos, con independencia del margen que quede en el límite primario; ante un error de límite secundario sin esa cabecera, espera al menos un minuto.
• Envía las solicitudes de escritura en serie y con al menos un segundo de separación, tal como recomienda GitHub frente a los límites secundarios.
• En cargas de trabajo de sondeo (polling), envía If-None-Match con un ETag guardado; un 304 autorizado no cuenta para el límite primario.

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

Trampas

Paginar con números page= construidos a mano a partir de per_page, lo cual falla en los endpoints que solo ofrecen paginación por cursor. Tratar la cabecera retry-after como opcional porque el x-ratelimit-remaining primario aún muestra margen. Suponer que todo error de límite de tasa es un 429: GitHub también usa 403, así que revisa las cabeceras y el mensaje de error antes de tratar un 403 como un problema de permisos.