Bewährte Methoden für die Verwendung der REST-API

Abfragen vermeiden

Abonniere Webhookereignisse, anstatt die API nach Daten abzufragen. Dies ermöglicht deiner Integration, innerhalb des API-Ratelimits zu bleiben. Weitere Informationen findest du unter Webhooks-Dokumentation.

Folgen von Umleitungen, die die API sendet

Wurde eine Ressource verschoben, gibt GitHub dies direkt über einen Umleitungsstatuscode an. Diesen Umleitungen solltest du unbedingt folgen. Jede Umleitungsantwort legt im Header Location den neuen URI fest, zu dem gewechselt werden soll. Wenn du eine Umleitung erhältst, solltest du deinen Code mit dem neuen URI aktualisieren, falls du einen veralteten Pfad anforderst, der möglicherweise entfernt wird.

Informationen zur Konfiguration deiner App für Umleitungen findest du in der Liste der HTTP-Statuscodes.

Vermeiden manueller URL-Analysen

Häufig enthalten API-Antworten Daten in Form von URLs. Wenn du beispielsweise ein Repository anforderst, erhältst du einen Schlüssel namens clone_url mit einer URL zum Klonen des Repositorys.

Aus Stabilitätsgründen solltest du diese Daten nicht analysieren oder versuchen, das Format zukünftiger URLs daraus zu erstellen. Deine App funktioniert bei einer Änderung der URL möglicherweise nicht mehr.

Wenn du beispielsweise mit paginierten Ergebnissen arbeitest, erscheint es zunächst verlockend, URLs durch Anfügen von ?page=<number> zu erstellen. Widerstehe dieser Versuchung. Weitere Informationen zum sicheren Folgen paginierter Ergebnisse findest du unter Verwenden der Paginierung in der REST-API.

Umgang mit Ratenbegrenzungen

Die Ratenbegrenzung der GitHub-API sorgt dafür, dass die API schnell und für alle verfügbar ist.

Bei Erreichen einer Ratenbegrenzung musst du die Ausführung von Anforderungen aussetzen, bis der im x-ratelimit-reset-Header angegebene Zeitraum abgelaufen ist. Ansonsten wird deine Integration möglicherweise gesperrt. Weitere Informationen findest du unter Ressourcen in der REST-API.

Umgang mit sekundären Ratenbegrenzungen

GitHub kann auch sekundäre Ratenbegrenzungen verwenden, um die API-Verfügbarkeit sicherzustellen. Weitere Informationen findest du unter Ressourcen in der REST-API.

Befolge mit deiner Anwendung die folgenden Richtlinien, um unterhalb des Grenzwerts zu bleiben:

Sende authentifizierte Anforderungen, oder verwende die Client-ID und das Geheimnis deiner Anwendung. Nicht authentifizierte Anforderungen unterliegen aggressiveren Ratenbegrenzungen.
Sende Anforderungen für einzelne Benutzer*innen oder eine einzelne Client-ID nacheinander. Sende solche Anforderungen nicht gleichzeitig.
Warte bei vielen POST-, PATCH-, PUT- oder DELETE-Anforderungen für einzelne Benutzer*innen oder eine einzelne Client-ID mindestens eine Sekunde zwischen den jeweiligen Anforderungen.
Wenn eine Einschränkung aktiv ist, solltest du abwarten, bevor du deine Anforderung wiederholst.
- Wenn der Antwortheader Retry-After vorhanden ist, wiederhole deine Anforderung nach der im Header angegebenen Zeit. Der Wert des Retry-After-Headers muss eine ganze Zahl sein, die für die Anzahl der Sekunden steht, die vor einer erneuten Anforderung verstreichen soll. So bedeutet Retry-After: 30 beispielsweise, dass mit dem Senden weiterer Anforderungen 30 Sekunden gewartet werden soll.
- Wenn der x-ratelimit-remaining-Header 0 lautet, wiederhole deine Anforderung nach dem im x-ratelimit-reset-Header angegebenen Zeitraum. Der x-ratelimit-reset-Header ist immer ein Integer, der die Zeit in UTC-Epochensekunden darstellt, nach der das aktuelle Ratenlimitfenster zurückgesetzt wird.
- Lass andernfalls eine exponentiell länger werdende Zeitspanne zwischen den Wiederholungsversuchen verstreichen und gib nach einer bestimmten Anzahl von Wiederholungsversuchen einen Fehler aus.

GitHub behält sich das Recht vor, diese Richtlinien bei Bedarf zu ändern, um die Verfügbarkeit sicherzustellen.

Umgang mit API-Fehlern

Obwohl dein Code keine Fehler enthält, kann es vorkommen, dass beim Zugreifen auf die API nacheinander mehrere Fehler auftreten.

Wiederholte Statuscodes vom Typ 4xx und 5xx solltest du nicht ignorieren. Stelle stattdessen sicher, dass die Interaktion mit der API korrekt ausgeführt wird. Wenn z. B. ein Endpunkt eine Zeichenfolge anfordert, du aber einen numerischen Wert übergibst, erhältst du einen Überprüfungsfehler vom Typ 5xx, und dein Aufruf wird nicht erfolgreich ausgeführt. Ebenso verursacht der Zugriffsversuch auf einen nicht autorisierten oder nicht vorhandenen Endpunkt einen Fehler vom Typ 4xx.

Wenn du wiederholte Überprüfungsfehler bewusst ignorierst, wird deine App möglicherweise wegen missbräuchlicher Nutzung gesperrt.