GitHub-REST-API: Paginierung und Auswertung der Header für primäre und sekundäre Rate Limits

Worum es geht

Die Paginierungsanleitung von GitHub zeigt einen link-Antwort-Header wie <...?page=2>; rel="prev", <...?page=4>; rel="next", <...?page=515>; rel="last" und weist Clients an, diese URLs direkt zu verwenden, statt Seiten-URLs selbst zu bilden: "The URL for the next page is followed by rel="next"." Je nach Endpunkt verwenden diese URLs page, before/after oder since. Laut GitHub-Dokumentation gilt: "for most endpoints, the maximum value of per_page is 100"; ein höherer Wert wird stillschweigend reduziert und nicht abgelehnt. Primäre Rate Limits werden bei jeder Antwort über x-ratelimit-limit, x-ratelimit-remaining, x-ratelimit-used, x-ratelimit-reset (UTC-Epochensekunden) und x-ratelimit-resource (gibt an, gegen welchen Bucket die Anfrage gezählt wurde) gemeldet. Davon getrennt erzwingt GitHub sekundäre Rate Limits. Dokumentierte Obergrenzen sind unter anderem höchstens 100 gleichzeitige Anfragen, 900 Punkte pro Minute für REST-API-Endpunkte, 90 Sekunden CPU-Zeit pro 60 Sekunden Echtzeit und höchstens 80 inhaltserzeugende Anfragen pro Minute (500 pro Stunde). Wird eine der beiden Limitarten überschritten, folgt 403 oder 429. Eine Antwort auf ein sekundäres Limit kann retry-after enthalten. Fehlt der Header, soll laut GitHub bis x-ratelimit-reset gewartet werden, wenn x-ratelimit-remaining gleich 0 ist, "otherwise, wait for at least one minute before retrying"; bei wiederholtem Auftreten ist mit exponentiell wachsenden Wartezeiten zu reagieren. Die Best-Practices-Seite von GitHub ergänzt, dass eine bedingte Anfrage "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."

Warum es wichtig ist

Seiten-URLs von Hand zu bauen funktioniert nicht mehr, sobald GitHub Query-Parameter ändert (sie unterscheiden sich bereits zwischen Endpunkten mit Seitennummern und Endpunkten mit Cursorn). Wird der retry-after-Header eines sekundären Limits ignoriert, weil das primäre Kontingent noch gut gefüllt ist, führt das häufig zu einer vorübergehenden Sperre, obwohl noch primäres Kontingent übrig ist.

So wird es angewendet

• Der URL der Relation rel="next" aus dem link-Header unverändert folgen; aufhören, sobald keine next-Relation mehr vorhanden ist.
• Bei leselastigen Jobs per_page=100 anfordern, um die Zahl der Roundtrips zu minimieren, und nie davon ausgehen, dass ein grösserer angeforderter Wert übernommen wurde.
• x-ratelimit-remaining und x-ratelimit-reset überwachen; schon deutlich vor Erreichen von null drosseln, statt erst auf ein 403/429 zu reagieren.
• Bei jeder Antwort mit retry-after mindestens so viele Sekunden warten, unabhängig vom verbleibenden primären Kontingent; bei einem Fehler wegen eines sekundären Limits ohne diesen Header mindestens eine Minute warten.
• Schreibende Anfragen seriell und mit mindestens einer Sekunde Abstand senden, wie GitHub es im Hinblick auf sekundäre Limits empfiehlt.
• Bei Polling-Workloads If-None-Match mit einem gespeicherten ETag senden; ein autorisiertes 304 wird nicht auf das primäre Limit angerechnet.

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

Stolpersteine

Paginieren mit page=-Nummern, die von Hand aus per_page berechnet werden; das scheitert bei Endpunkten, die nur Cursor-Paginierung anbieten. Den retry-after-Header als optional behandeln, weil x-ratelimit-remaining des primären Limits noch Spielraum zeigt. Annehmen, jeder Rate-Limit-Fehler sei ein 429: GitHub verwendet auch 403, daher vor der Einordnung eines 403 als Berechtigungsproblem Header und Fehlermeldung prüfen.