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

Abfragen vermeiden

Abonnieren Sie Webhook-Ereignisse, anstatt die API nach Daten abzufragen. Dies ermöglicht deiner Integration, innerhalb des API-Ratelimits zu bleiben. Weitere Informationen finden Sie unter Webhooks-Dokumentation.

Wenn Sie Webhooks nicht verwenden können und die API abfragen müssen, können Sie die Abfrage so effizient wie möglich durchführen, um zu vermeiden, dass die Häufigkeitsgrenze überschritten wird:

• Rufen Sie nur so oft wie nötig auf einem festen Zeitplan ab. Wenn eine Antwort einen x-poll-interval Header enthält, warten Sie mindestens so viele Sekunden, bevor Sie denselben Endpunkt erneut abrufen.
• Stellen Sie authentifizierte bedingte Anforderungen vor, sodass unveränderte Daten nicht auf Ihr Primäres Ratelimit zählen. Weitere Informationen finden Sie unter Verwenden von bedingten Anforderungen.
• Fordern Sie nur die benötigten Daten an, und halten Sie Antworten stabil, sodass mehr Ihrer Umfragen zurückgegeben werden 304 Not Modified. Weitere Informationen finden Sie unter Stellen von Anforderungen, die zwischengespeichert werden können.

Authentifizierte Anfragen stellen

Authentifizierte Anforderungen haben eine höhere primäre Ratenbegrenzung als nicht authentifizierte Anforderungen. Um eine Überschreitung der Anfragerate zu vermeiden, solltest du authentifizierte Anfragen stellen. Weitere Informationen finden Sie unter Ratenbegrenzungen für die REST-API.

Gleichzeitige Anforderungen vermeiden

Um zu vermeiden, dass sekundäre Ratenbegrenzungen überschritten werden, solltest du Anforderungen seriell statt gleichzeitig vornehmen. Um dies zu erreichen, kannst du ein Warteschlangensystem für Anforderungen implementieren.

Zwischen veränderlichen Anforderungen pausieren

Warte bei vielen POST-, PATCH-, PUT- oder DELETE-Anforderungen mindestens eine Sekunde zwischen den jeweiligen Anforderungen. Auf diese Weise kannst du sekundäre Ratenbegrenzungen vermeiden.

Ratenbegrenzungsfehler entsprechend beheben

Wenn Sie einen Ratenbegrenzungsfehler erhalten, sollten Sie gemäß den folgenden Richtlinien das Erstellen von Anforderungen vorübergehend beenden:

• Wenn der Antwortheader retry-after vorhanden ist, sollten Sie Ihre Anforderung erst nach Ablauf dieser Sekundenzahl erneut übermitteln.
• Wenn der x-ratelimit-remaining-Header 0 lautet, sollten Sie die Anforderung erst senden, nachdem die im x-ratelimit-reset-Header angegebene Zeit abgelaufen ist. Der x-ratelimit-reset-Header ist in UTC-Epochensekunden angegeben.
• Warten Sie andernfalls mindestens eine Minute, bevor Sie den Vorgang wiederholen. Wenn Ihre Anforderung aufgrund einer sekundären Ratenbegrenzung weiterhin fehlschlägt, warten Sie auf eine exponentiell steigende Zeitspanne zwischen Wiederholungen, und lösen Sie nach einer bestimmten Anzahl von Wiederholungen einen Fehler aus.

Wenn Sie weiterhin Anfragen stellen, während Sie von einer Ratenbegrenzung betroffen sind, kann dies zu einer Sperrung Ihrer Integration führen.

Folgt Weiterleitungen

Die GitHub REST-API verwendet ggf. die HTTP-Umleitung. Sie sollten davon ausgehen, dass jede Anforderung zu einer Umleitung führen kann. Der Empfang einer HTTP-Umleitung ist kein Fehler, und Sie sollten dieser Umleitung folgen.

Ein 301-Statuscode steht für eine permanente Umleitung. Sie sollten Ihre Anforderung an die durch den location-Header angegebene URL wiederholen. Darüber hinaus sollten Sie Ihren Code aktualisieren, um diese URL für zukünftige Anforderungen zu verwenden.

Ein 302- oder 307-Statuscode steht für eine temporäre Umleitung. Sie sollten Ihre Anforderung an die durch den location-Header angegebene URL wiederholen. Sie sollten ihren Code jedoch nicht aktualisieren, um diese URL für zukünftige Anforderungen zu verwenden.

Andere Umleitungsstatuscodes können gemäß der HTTP-Spezifikation verwendet werden.

URLs nicht manuell parsen

Viele API-Endpunkte geben URL-Werte für Felder im Antworttext zurück. Sie sollten nicht versuchen, diese URLs zu parsen oder die Struktur zukünftiger URLs vorherzusagen. Dies kann dazu führen, dass Ihre Integration nicht mehr funktioniert, wenn GitHub die Struktur der URL in Zukunft ändert. Stattdessen sollten Sie nach einem Feld suchen, das die benötigten Informationen enthält. Beispielsweise gibt der Endpunkt für die Erstellung eines Issue ein html_url-Feld mit einem Wert wie https://github.com/octocat/Hello-World/issues/1347 und ein number-Feld mit einem Wert wie 1347 zurück. Wenn Sie die Nummer des Issue kennen müssen, verwenden Sie das number-Feld, anstatt das html_url-Feld zu parsen.

Ebenso sollten Sie nicht versuchen, Paginierungsabfragen manuell zu erstellen. Stattdessen sollten Sie die Linkheader verwenden, um zu bestimmen, welche Seiten von Ergebnissen Sie anfordern können. Weitere Informationen finden Sie unter Verwenden der Paginierung in der REST-API.

Verwenden bedingter Anforderungen

Die meisten Endpunkte geben einen etag-Header zurück, und viele Endpunkte geben einen last-modified-Header zurück. Du kannst die Werte dieser Header verwenden, um bedingte GET-Anforderungen durchzuführen. Wenn die Antwort nicht geändert wurde, erhalten Sie eine 304 Not Modified-Antwort. Das Erstellen einer bedingten Anforderung wird nicht zu deinem primären Ratenbegrenzung gezählt, wenn eine 304-Antwort zurückgegeben wird und die Anforderung während der ordnungsgemäßen Autorisierung mit einem Authorization-Header durchgeführt wurde. Dies macht bedingte Anforderungen besonders nützlich, wenn Sie einen Endpunkt abfragen, da jede 304 Not Modified Antwort schnell ist und ihre Rate-Grenze nicht verwendet.

Ersetzen Sie YOUR-TOKEN in den folgenden Beispielen ihr Zugriffstoken. Ersetzen Sie es durch das Konto, das das Repository besitzt, und ersetzen Sie REPO-OWNER``REPO-NAME es durch den Namen des Repositorys.

So stellen Sie eine bedingte Anforderung mit einer etag:

1. Stellen Sie eine Anforderung vor, und speichern Sie den Wert des etag Headers aus der Antwort.

   curl --include --header "Authorization: Bearer YOUR-TOKEN" http(s)://HOSTNAME/api/v3/repos/REPO-OWNER/REPO-NAME/pulls
   

   Die Antwort enthält einen etag Header:

   HTTP/2 200
   etag: "644b5b0155e6404a9cc4bd9d8b1ae730"
   

2. Senden Sie in Ihrer nächsten Anforderung an dieselbe URL den gespeicherten Wert in der if-none-match Kopfzeile.

   curl --include --header "Authorization: Bearer YOUR-TOKEN" --header 'if-none-match: "644b5b0155e6404a9cc4bd9d8b1ae730"' http(s)://HOSTNAME/api/v3/repos/REPO-OWNER/REPO-NAME/pulls
   

   Wenn sich die Daten nicht geändert haben, erhalten Sie eine 304 Not Modified Antwort, die nicht auf ihr Primäres Zinslimit angerechnet wird:

   HTTP/2 304
   

Sie können auch die last-modified Kopfzeile verwenden. Wenn beispielsweise eine vorherige Anforderung den last-modified-Headerwert Wed, 25 Oct 2023 19:17:59 GMT zurückgegeben hat, können Sie den if-modified-since-Header in einer zukünftigen Anforderung verwenden:

curl --include --header "Authorization: Bearer YOUR-TOKEN" --header 'if-modified-since: Wed, 25 Oct 2023 19:17:59 GMT' http(s)://HOSTNAME/api/v3/repos/REPO-OWNER/REPO-NAME

Bedingte Anforderungen für unsichere Methoden wie POST, PUT, PATCH und DELETE werden nur unterstützt, wenn in der Dokumentation für einen bestimmten Endpunkt keine anderweitigen Informationen angegeben werden.

Erstellen von Anforderungen, die zwischengespeichert werden können

Eine bedingte Anforderung spart Ihnen nur Zeit und Zinslimit, wenn der Endpunkt zurückgibt 304 Not Modified. Der Endpunkt gibt zurück 304 , wenn sich die angeforderte Darstellung seit dem Speichern etag oder last-modified Wert nicht geändert hat. Nicht verknüpfte Antwortheader, z. B. das Datum, können sich weiterhin unterscheiden. Um Antworten bei der Umfrage wahrscheinlicher zu machen 304 , halten Sie Ihre Anforderungen stabil und spezifisch.

Fordern Sie nur die benötigten Daten an. Eine kleinere, spezifischere Antwort ändert sich weniger oft, sodass sie häufiger zurückgegeben wird 304 Not Modified . Um beispielsweise die Pullanforderungen für eine Verzweigung zu überprüfen, filtern Sie die Liste nach dieser Verzweigung, anstatt jede Pullanforderung aufzulisten und die Ergebnisse selbst zu durchsuchen. Ersetzen Sie HEAD-OWNER durch das Konto, das die Head Branch besitzt. Für eine Pullanforderung von einer Verzweigung ist dies das Konto, das die Verzweigung besitzt. Ersetzen Sie BRANCH-NAME ihn durch den Namen der Verzweigung, und codieren Sie sie, wenn sie Sonderzeichen wie # oder &:

curl --include --header "Authorization: Bearer YOUR-TOKEN" "http(s)://HOSTNAME/api/v3/repos/REPO-OWNER/REPO-NAME/pulls?head=HEAD-OWNER:BRANCH-NAME"

Wenn Sie eine Liste durchlaufen, verwenden Sie eine stabile Sortierreihenfolge. Einige Parameter, z sort=updated. B. , ordnen Sie die Liste neu an, wenn sich ein Element ändert. Wenn ein Element an eine neue Position verschoben wird, werden die Elemente zwischen den alten und neuen Positionen auf verschiedene Seiten verschoben, sodass bereits abgerufene Seiten neue Daten anstelle von 304 Not Modified. Eine stabile Reihenfolge, z. B. die Standardeinstellung, beendet Aktualisierungen vorhandener Elemente, indem die Liste neu angeordnet wird, obwohl das Hinzufügen oder Entfernen von Elementen weiterhin Einträge auf anderen Seiten verschieben kann.

Verwenden Sie bei jedem Abruf derselben Daten dieselben Parameter. Eine andere Seitengröße, Seitenzahl oder ein anderer Filter erzeugt eine andere Antwort mit einem anderen etag.

Fehler nicht ignorieren

Wiederholte 4xx- und 5xx-Fehlercodes sollten nicht ignoriert werden. Stattdessen sollten Sie sicherstellen, dass Sie ordnungsgemäß mit der API interagieren. Wenn z. B. ein Endpunkt eine Zeichenfolge anfordert, du aber einen numerischen Wert übergibst, erhältst du einen Überprüfungsfehler.. Ebenso verursacht der Zugriffsversuch auf einen nicht autorisierten oder nicht vorhandenen Endpunkt einen Fehler vom Typ 4xx.

Wenn Sie abfragen und eine Ressource wiederholt eine 404 Not Found Antwort zurückgibt, fordern Sie sie nicht bei jeder Umfrage an. Stellen Sie zunächst sicher, dass dies 404 nicht durch Authentifizierung oder Autorisierung verursacht wird. GitHub gibt eine 404 Not Found Antwort anstelle einer 403 Forbidden Antwort für einige private Ressourcen zurück, wenn Ihre Anmeldeinformationen keinen Zugriff gewähren, sodass eine 404 Ressource nicht immer bedeutet, dass die Ressource nicht vorhanden ist. Weitere Informationen finden Sie unter Problembehandlung der REST-API. Nachdem Sie bestätigt haben, dass Ihre Anmeldeinformationen korrekt sind, warten Sie viel länger, bevor Sie die Überprüfung erneut durchführen, oder überprüfen Sie erneut, wenn Sie einen Grund haben, zu glauben, dass die Ressource jetzt vorhanden ist. Wenn Sie wiederholt eine fehlende Ressource anfordern, wird Ihr Zinslimit verschwendet und kann ein sekundäres Zinslimit auslösen.

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

Weiterführende Lektüre

• Bewährte Methoden für die Verwendung von Webhooks
• Bewährte Methoden zum Erstellen einer GitHub-App