ポーリングを回避する
API でデータをポーリングする代わりに、Webhook イベントをサブスクライブしてください。 これにより、統合が API レート制限内に留まるのに役立ちます。 詳しくは、「Webhook ドキュメント」を参照してください。
APIが送信するあらゆるAPIに従う
GitHubは、リダイレクトのステータスコードを提供することにより、リソースがいつ移動したかを明示します。 このリダイレクトに従ってください。 すべてのリダイレクト応答では、Location ヘッダーに、移動する新しい URI を設定します。 リダイレクトを受け取ったら、削除する可能性がある非推奨のパスをリクエストしている場合、新しいURIにしたがってコードを更新するようお勧めします。
リダイレクトに従うようにアプリを設計するときに注意する必要がある HTTP 状態コードスの一覧を用意してあります。
手動でURLをパースしない
APIレスポンスには、URLの形でデータが含まれていることがよくあります。 たとえば、リポジトリを要求するときは、リポジトリをクローンするために使用できる URL を含む clone_url というキーを送信します。
アプリケーションの安定性を保つため、このデータをパースしようとしたり、先のURLの形式を予想して作成しようとしたりしないでください。 URLを変更した場合、アプリケーションが壊れるおそれがあります。
たとえば、ページネーションされた結果を処理するときは、末尾に ?page=<number> の付いた URL を構築したいことがよくあります。 この誘惑に負けてはなりません。 ページネーションされた結果を安全に扱う方法については、「REST API 内での改ページ位置の自動修正の使用」を参照してください。
レート制限の扱い
GitHub API のレート制限により、API が高速で、すべてのユーザーが利用できることが保証されます。
レート制限に達した場合は、x-ratelimit-reset ヘッダーで指定された時間が経過するまで要求を停止する必要があります。 そうしないと、統合が禁止される場合があります。 詳しくは、「REST API のリソース」を参照してください。
セカンダリレート制限の扱い
GitHub では、API の可用性を確保するためにセカンダリ レート制限が使用される場合もあります。 詳しくは、「REST API のリソース」を参照してください。
この制限に到達することを避けるため、アプリケーションは以下のガイドラインに従うようにしてください。
- 認証済みのリクエストを行うか、アプリケーションのクライアントIDとシークレットを使用してください。 認証されていない要求には、より強いセカンダリ レート制限が適用されます。
- 単一のユーザまたはクライアントIDに順番にリクエストを行ってください。 単一のユーザーまたはクライアント ID の要求を同時に行わないでください。
- 単一のユーザーまたはクライアント ID で多数の
POST、PATCH、PUT、DELETE要求を行う場合は、各要求の間を少なくとも 1 秒空けてください。 - 制限されている場合は、要求を再試行する前に待ちます。
Retry-After応答ヘッダーが存在する場合は、ヘッダーで指定された時間より後に要求を再試行してください。Retry-Afterヘッダーの値は常に整数であり、もう一度要求を行う前に待機する秒数を示します。 たとえば、Retry-After: 30は、次の要求を送信する前に 30 秒待つ必要があることを意味します。x-ratelimit-remainingヘッダーが0の場合、x-ratelimit-resetヘッダーで指定された時間より後に要求を再試行してください。x-ratelimit-resetヘッダーは常に、現在のレート制限ウィンドウが UTC エポック秒数でリセットされる時間を表す整数になります。- それ以外の場合は、再試行の間の時間が指数関数的に増えるのを待機し、特定の回数の再試行の後にエラーをスローします。
GitHub は、可用性確保のため必要に応じてこれらのガイドラインを変更する権利を留保します。
APIエラーの扱い
あなたのコードが決してバグを発生させなかったとしても、APIにアクセスしようとするとき立て続けにエラーが発生することがるかもしれません。
繰り返し表示される 4xx や 5xx の状態コードを無視せず、API と正しくやり取りしていることを確認する必要があります。 たとえば、エンドポイントが文字列を要求しているのに数値を渡している場合は、5xx 検証エラーを受け取り、呼び出しは成功しません。 同様に、許可されていないエンドポイントまたは存在しないエンドポイントにアクセスしようとすると、4xx エラーが発生します。
繰り返し発生する検証エラーを意図的に無視すると、不正利用によりアプリケーションが停止されることがあります。