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.

Authentifizierte Anforderungen stellen

Authentifizierte Anforderungen haben eine höhere primäre Ratenbegrenzung als nicht authentifizierte Anforderungen. Um eine Überschreitung der Ratenbegrenzung zu vermeiden, solltest du authentifizierte Anforderungen stellen. Weitere Informationen findest du 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 mutativen Anforderungen anhalten

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 Anforderung erst nach Ablauf der im x-ratelimit-reset-Header angegebenen Zeit erneut senden. 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 die Ratenbegrenzung eingeschränkt ist, kann dies zu einer Sperrung Ihrer Integration führen.

Follow Redirects

Die GitHub AE-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 die Integration unterbrochen wird, 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 findest du unter Verwenden der Paginierung in der REST-API.

Bei Bedarf bedingte Anforderungen verwenden

Die meisten Endpunkte geben einen etag-Header zurück, und viele Endpunkte geben einen last-modified-Header zurück. Sie können die Werte dieser Header verwenden, um bedingte Anforderungen zu stellen. Wenn die Antwort nicht geändert wurde, erhalten Sie eine 304 Not Modified-Antwort. Wenn eine bedingte Anforderung ausgeführt wird, wird diese nicht auf Ihre primäre Ratenbegrenzung angerechnet, wenn eine 304-Antwort zurückgegeben wird.

Wenn beispielsweise eine vorherige Anforderung den etag-Headerwert 644b5b0155e6404a9cc4bd9d8b1ae730zurückgegeben hat, können Sie den if-none-match-Header in einer zukünftigen Anforderung verwenden:

curl https://<em>HOSTNAME</em>/api/v3/meta --include --header 'if-none-match: "644b5b0155e6404a9cc4bd9d8b1ae730"'

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 https://<em>HOSTNAME</em>/api/v3/repos/github/docs --include --header 'if-modified-since: Wed, 25 Oct 2023 19:17:59 GMT'

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 du wiederholte Überprüfungsfehler bewusst ignorierst, wird deine App möglicherweise wegen missbräuchlicher Nutzung gesperrt.