Paginer l'API REST de GitHub et lire les en-têtes des limites de débit primaires et secondaires

Ce que c'est

Le guide de pagination de GitHub présente un en-tête de réponse link de la forme <...?page=2>; rel="prev", <...?page=4>; rel="next", <...?page=515>; rel="last" et demande aux clients d'utiliser directement ces URL plutôt que de construire eux-mêmes les URL des pages : « The URL for the next page is followed by rel="next". » Selon le point de terminaison, ces URL reposent sur page, sur before/after ou sur since. La documentation de GitHub précise : « for most endpoints, the maximum value of per_page is 100, » et une valeur supérieure est ramenée silencieusement à ce plafond au lieu d'être rejetée. Les limites de débit primaires sont indiquées dans chaque réponse par x-ratelimit-limit, x-ratelimit-remaining, x-ratelimit-used, x-ratelimit-reset (en secondes depuis l'epoch, UTC) et x-ratelimit-resource (le compteur auquel la requête a été imputée). GitHub applique en outre des limites de débit secondaires ; les plafonds documentés comprennent au maximum 100 requêtes simultanées, 900 points par minute pour les points de terminaison de l'API REST, 90 secondes de temps CPU par tranche de 60 secondes de temps réel, et au maximum 80 requêtes générant du contenu par minute (500 par heure). Le dépassement de l'un ou l'autre type de limite renvoie 403 ou 429 ; une réponse liée à une limite secondaire peut contenir retry-after, et lorsque ce n'est pas le cas, GitHub indique d'attendre jusqu'à x-ratelimit-reset si x-ratelimit-remaining vaut 0, « otherwise, wait for at least one minute before retrying », avec un backoff exponentiel en cas de nouvel échec. La page de bonnes pratiques de GitHub ajoute qu'une requête conditionnelle « 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. »

Pourquoi c'est important

Construire les URL de page à la main cesse de fonctionner dès que GitHub modifie ses paramètres de requête (ils diffèrent déjà entre les points de terminaison à numéros de page et ceux à curseur). Ignorer l'en-tête retry-after des limites secondaires parce que le solde de la limite primaire est confortable est un moyen courant de se faire bloquer temporairement alors qu'il reste du quota primaire.

Comment l'appliquer

• Suivre telle quelle l'URL rel="next" de l'en-tête link ; s'arrêter lorsqu'aucune relation next n'est présente.
• Demander per_page=100 pour les tâches surtout en lecture afin de limiter les allers-retours, et ne jamais supposer qu'une valeur plus grande a été acceptée.
• Suivre x-ratelimit-remaining et x-ratelimit-reset ; ralentir bien avant que le solde n'atteigne zéro plutôt que de ne réagir qu'à un 403/429.
• Dès qu'une réponse contient retry-after, attendre au moins ce nombre de secondes, quelle que soit la marge restante sur la limite primaire ; en cas d'erreur de limite secondaire sans cet en-tête, attendre au moins une minute.
• Envoyer les requêtes d'écriture en série, avec au moins une seconde d'écart, comme GitHub le recommande face aux limites secondaires.
• Pour les charges de travail de type polling, envoyer If-None-Match avec un ETag mémorisé ; un 304 autorisé n'est pas décompté de la limite primaire.

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

Pièges

Paginer avec des numéros page= construits à la main à partir de per_page, ce qui échoue sur les points de terminaison n'offrant qu'une pagination par curseur. Considérer l'en-tête retry-after comme facultatif parce que x-ratelimit-remaining indique encore une marge sur la limite primaire. Supposer que toute erreur de limite de débit est un 429 : GitHub utilise aussi 403, il faut donc vérifier les en-têtes et le message d'erreur avant de traiter un 403 comme un problème de permissions.