REST API を使用するためのベスト プラクティス

GitHub の API を使用する場合は、次のベスト プラクティスに従います。

この記事で

ポーリングを回避する

API でデータをポーリングする代わりに、Webhook イベントをサブスクライブしてください。 これにより、統合が API レート制限内に留まるのに役立ちます。 詳しくは、「Webhook ドキュメント」をご覧ください。

認証済みのリクエストを出します。

認証された要求のプライマリ レート制限は、認証されていない要求よりも高くなります。 レート制限を超えないようにするには、認証済みの要求を行う必要があります。 詳しくは、「REST API のレート制限」をご覧ください。

同時にリクエストを行うことを避けてください。

セカンダリ レート制限を超えないようにするには、同時に要求するのではなく、順次要求を行う必要があります。 これを実現するために、要求のキュー システムを実装できます。

変更要求の間で一時停止する

多くの POST、PATCH、PUT、DELETE リクエストを行う場合は、各リクエストの間を少なくとも 1 秒空けてください。 これは、セカンダリ レート制限を回避するのに役立ちます。

レート制限エラーを適切に処理する

レート制限エラーが発生した場合は、次のガイドラインに従って一時的に要求を停止することが必要です。

  •         `retry-after` 応答ヘッダーが存在する場合は、その秒数が経過するまで要求を再試行しないでください。

  •         `x-ratelimit-remaining` ヘッダーが `0` の場合、`x-ratelimit-reset` ヘッダーで指定された時刻 (UTC エポック秒数)が過ぎる まで要求を再試行しないでください。 
        `x-ratelimit-reset` ヘッダーは UTC エポック秒単位です。
  • それ以外の場合は、少なくとも 1 分間待ってから再試行します。 要求が二次レート制限により継続して失敗する場合は、再試行の間は指数関数的に増加する時間を待ち、特定の回数の再試行の後にエラーを発生させます。

レート制限中に要求を続けると、統合を禁止する可能性があります。

プライマリ レート制限を超えた要求など、organization の API アクティビティを表示する方法については、「組織内での API のインサイトの表示」をご覧ください。

リダイレクトへの追従

GitHub REST API では、必要に応じて HTTP リダイレクトが使われます。 クライアントは、要求がリダイレクトされる可能性があることを想定する必要があります。 HTTP リダイレクトの受信はエラーではなく、クライアントはそのリダイレクトに従う必要があります。

          `301` 状態コードは、永続的なリダイレクトを示しています。 ヘッダー`location`で指定された URL に要求を繰り返す必要があります。 さらに、今後の要求にこの URL を使用するようにコードを更新する必要があります。

          `302` または `307` 状態コードは、一時的なリダイレクトを示しています。 `location` ヘッダーで指定された URL に要求を繰り返すことが必要です。 ただし、今後の要求にこの URL を使用するようにコードを更新しないでください。

その他のリダイレクトステータスコードは、HTTP仕様に従って使用できます。

URL を手動で解析しない

多くの API エンドポイントは、応答本文のフィールドの URL 値を返します。 これらの URL を解析したり、将来の URL の構造を予測したりしないでください。 これにより、GitHub が将来 URL の構造を変更すると、統合が中断する可能性があります。 代わりに、必要な情報を含むフィールドを探す必要があります。 例えば、問題作成のエンドポイントは、類似の値を持つhtml_urlフィールドと類似のhttps://github.com/octocat/Hello-World/issues/1347、number値を持つ1347フィールドを返します。 問題の番号を知る必要がある場合は、number フィールドを使用し、html_url フィールドを解析しないでください。

同様に、ページネーションクエリを手動で作成しないでください。 代わりに、リンク ヘッダーを使用して、要求できる結果のページを決定する必要があります。 詳しくは、「REST API でのページネーションの使用」をご覧ください。

必要に応じて条件付き要求を使用する

ほとんどのエンドポイントはヘッダーを etag 返し、多くのエンドポイントはヘッダーを last-modified 返します。 これらのヘッダーの値を使用して、条件付き GET 要求を行うことができます。 応答が変更されていない場合は、応答を 304 Not Modified 受け取ります。 304 ヘッダーを使って適切に認可された状態で Authorization 応答が返された場合、条件付き要求を行っても、プライマリ レート制限にはカウントされません。

たとえば、以前の要求で 644b5b0155e6404a9cc4bd9d8b1ae730 という etag ヘッダー値を受け取った場合、将来の要求ではこの if-none-match ヘッダーを使用できます。

curl -H "Authorization: Bearer YOUR-TOKEN" https://api.github.com/meta --include --header 'if-none-match: "644b5b0155e6404a9cc4bd9d8b1ae730"'

たとえば、前の要求でlast-modifiedヘッダー値Wed, 25 Oct 2023 19:17:59 GMTが返された場合、将来の要求でif-modified-sinceヘッダーを使用できます。

curl -H "Authorization: Bearer YOUR-TOKEN" https://api.github.com/repos/github/docs --include --header 'if-modified-since: Wed, 25 Oct 2023 19:17:59 GMT'

          `POST`、`PUT`、`PATCH`、`DELETE` などの安全でないメソッドの条件付き要求は、特定のエンドポイントに関するドキュメントに特に記載されていない限り、サポートされません。

エラーを無視しない

繰り返し発生する4xxおよび5xxエラーコードを無視しないでください。 代わりに、API と正しく対話していることを確認する必要があります。 たとえば、エンドポイントが文字列を要求しているのに数値を渡している場合は、 検証エラーを受け取り、呼び出しは成功しません。 同様に、許可されていないエンドポイントまたは存在しないエンドポイントにアクセスしようとすると、4xx エラーが発生します。

繰り返し発生する検証エラーを意図的に無視すると、不正利用によりアプリケーションが停止されることがあります。

参考資料

  •         [AUTOTITLE](/webhooks/using-webhooks/best-practices-for-using-webhooks)

  •         [AUTOTITLE](/apps/creating-github-apps/about-creating-github-apps/best-practices-for-creating-a-github-app)