{"meta":{"title":"REST API を使用するためのベスト プラクティス","intro":"GitHubの API を使用する場合は、次のベスト プラクティスに従ってください。","product":"REST API","breadcrumbs":[{"href":"/ja/rest","title":"REST API"},{"href":"/ja/rest/using-the-rest-api","title":"REST API を使用して"},{"href":"/ja/rest/using-the-rest-api/best-practices-for-using-the-rest-api","title":"ベスト プラクティス"}],"documentType":"article"},"body":"# REST API を使用するためのベスト プラクティス\n\nGitHubの API を使用する場合は、次のベスト プラクティスに従ってください。\n\n## ポーリングを回避する\n\nAPI でデータをポーリングする代わりに、Webhook イベントをサブスクライブしてください。 これにより、統合が API レート制限内に留まるのに役立ちます。 詳しくは、「[Webhook ドキュメント](/ja/webhooks)」をご覧ください。\n\nWebhook を使用できず、API をポーリングする必要がある場合は、レート制限を超えないようにできるだけ効率的にポーリングします。\n\n* 必要な頻度でのみ、固定されたスケジュールに従ってポーリングします。 応答に `x-poll-interval` ヘッダーが含まれている場合は、同じエンドポイントをもう一度ポーリングする前に、少なくともその秒数待ちます。\n* 未変更のデータがプライマリ レート制限に対してカウントされないように、認証済みの条件付き要求を行います。 詳細については、「 [条件付き要求を使用する](#use-conditional-requests)」を参照してください。\n* 必要なデータのみを要求し、応答を安定させ、より多くのポーリングが `304 Not Modified`返されるようにします。 詳細については、「 [キャッシュ可能な要求を作成する](#make-requests-that-can-be-cached)」を参照してください。\n\n## 認証済みのリクエストを出します。\n\n認証された要求のプライマリ レート制限は、認証されていない要求よりも高くなります。 レート制限を超えないようにするには、認証済みの要求を行う必要があります。 詳しくは、「[REST API のレート制限](/ja/rest/using-the-rest-api/rate-limits-for-the-rest-api)」をご覧ください。\n\n## 同時にリクエストを行うことを避けてください。\n\nセカンダリ レート制限を超えないようにするには、同時に要求するのではなく、順次要求を行う必要があります。 これを実現するために、要求のキュー システムを実装できます。\n\n## 変更要求の間で一時停止する\n\n多くの `POST`、`PATCH`、`PUT`、`DELETE` リクエストを行う場合は、各リクエストの間を少なくとも 1 秒空けてください。 これは、セカンダリ レート制限を回避するのに役立ちます。\n\n## レート制限エラーを適切に処理する\n\nレート制限エラーが発生した場合は、次のガイドラインに従って一時的に要求を停止することが必要です。\n\n* `retry-after` 応答ヘッダーが存在する場合は、その秒数が経過するまで要求を再試行しないでください。\n* `x-ratelimit-remaining` ヘッダーが `0`、`x-ratelimit-reset` ヘッダーで指定された時刻 (UTC エポック秒数)が過ぎる まで要求を再試行しないでください。\n  `x-ratelimit-reset` ヘッダーは UTC エポック秒単位です。\n* それ以外の場合は、少なくとも 1 分間待ってから再試行します。 要求が二次レート制限により継続して失敗する場合は、再試行の間は指数関数的に増加する時間を待ち、特定の回数の再試行の後にエラーを発生させます。\n\nレート制限中に要求を続けると、統合を禁止する可能性があります。\n\n## リダイレクトへの追従\n\nGitHub REST API は、必要に応じて HTTP リダイレクトを使用します。 クライアントは、要求がリダイレクトされる可能性があることを想定する必要があります。 HTTP リダイレクトの受信はエラーではなく、クライアントはそのリダイレクトに従う必要があります。\n\n`301` 状態コードは、永続的なリダイレクトを示しています。 ヘッダー`location`で指定された URL に要求を繰り返す必要があります。 さらに、今後の要求にこの URL を使用するようにコードを更新する必要があります。\n\n`302` または `307` 状態コードは、一時的なリダイレクトを示しています。 ヘッダー`location`で指定された URL に要求を繰り返す必要があります。 ただし、今後の要求にこの URL を使用するようにコードを更新しないでください。\n\nその他のリダイレクトステータスコードは、HTTP仕様に従って使用できます。\n\n## URL を手動で解析しない\n\n多くの API エンドポイントは、応答本文のフィールドの URL 値を返します。 これらの URL を解析したり、将来の URL の構造を予測したりしないでください。 これにより、 GitHub が将来 URL の構造を変更すると、統合が中断する可能性があります。 代わりに、必要な情報を含むフィールドを探す必要があります。 例えば、問題作成のエンドポイントは、類似の値を持つ`html_url`フィールドと類似の`https://github.com/octocat/Hello-World/issues/1347`、`number`値を持つ`1347`フィールドを返します。 問題の番号を知る必要がある場合は、`number` フィールドを使用し、`html_url` フィールドを解析しないでください。\n\n同様に、ページネーションクエリを手動で作成しないでください。 代わりに、リンク ヘッダーを使用して、要求できる結果のページを決定する必要があります。 詳しくは、「[REST API でのページネーションの使用](/ja/rest/using-the-rest-api/using-pagination-in-the-rest-api)」をご覧ください。\n\n## 条件付き要求を使用する\n\nほとんどのエンドポイントはヘッダーを `etag` 返し、多くのエンドポイントはヘッダーを `last-modified` 返します。 これらのヘッダーの値を使用して、条件付き `GET` 要求を行うことができます。 応答が変更されていない場合は、応答を `304 Not Modified` 受け取ります。\n`304` ヘッダーを使って適切に認可された状態で `Authorization` 応答が返された場合、条件付き要求を行っても、プライマリ レート制限にはカウントされません。 これにより、エンドポイントをポーリングするときに条件付き要求が特に役立ちます。これは、各 `304 Not Modified` 応答が高速であり、レート制限を使用しないためです。\n\n次の例では、 `YOUR-TOKEN` をアクセス トークンに置き換えます。\n\n`etag`を使用して条件付き要求を行うには:\n\n1. 要求を行い、応答から `etag` ヘッダーの値を保存します。\n\n   ```shell\n   curl --include --header \"Authorization: Bearer YOUR-TOKEN\" https://api.github.com/repos/octocat/Spoon-Knife/pulls\n   ```\n\n   応答には、 `etag` ヘッダーが含まれています。\n\n   ```text\n   HTTP/2 200\n   etag: \"644b5b0155e6404a9cc4bd9d8b1ae730\"\n   ```\n\n2. 同じ URL への次の要求で、 `if-none-match` ヘッダーに保存された値を送信します。\n\n   ```shell\n   curl --include --header \"Authorization: Bearer YOUR-TOKEN\" --header 'if-none-match: \"644b5b0155e6404a9cc4bd9d8b1ae730\"' https://api.github.com/repos/octocat/Spoon-Knife/pulls\n   ```\n\n   データが変更されていない場合は、 `304 Not Modified` 応答が返されます。これは、プライマリ レート制限に対してカウントされません。\n\n   ```text\n   HTTP/2 304\n   ```\n\n`last-modified` ヘッダーを使用することもできます。 たとえば、前の要求で`last-modified`ヘッダー値`Wed, 25 Oct 2023 19:17:59 GMT`が返された場合、将来の要求で`if-modified-since`ヘッダーを使用できます。\n\n```shell\ncurl --include --header \"Authorization: Bearer YOUR-TOKEN\" --header 'if-modified-since: Wed, 25 Oct 2023 19:17:59 GMT' https://api.github.com/repos/octocat/Spoon-Knife\n```\n\n`POST`、`PUT`、`PATCH`、`DELETE` などの安全でないメソッドの条件付き要求は、特定のエンドポイントに関するドキュメントに特に記載されていない限り、サポートされません。\n\n## キャッシュ可能な要求を行う\n\n条件付き要求では、エンドポイントから `304 Not Modified`が返された場合にのみ、時間とレートの制限が節約されます。 エンドポイントは、`304`または`etag`値を保存してから要求した表現が変更されていない場合に`last-modified`を返します。日付などの関連のない応答ヘッダーは、引き続き異なる場合があります。 ポーリング時に `304` 応答の可能性を高めるために、要求を安定して具体的なものにします。\n\n必要なデータのみを要求します。 より小さく、より具体的な応答は頻繁に変更されないため、より頻繁に `304 Not Modified` 返されます。 たとえば、1 つのブランチのプル要求を確認するには、すべてのプル要求を一覧表示して自分で結果を検索するのではなく、そのブランチで一覧をフィルター処理します。\n`HEAD-OWNER`をヘッド ブランチを所有するアカウントに置き換えます。フォークからのプル要求の場合、これはフォークを所有するアカウントです。\n`BRANCH-NAME`をブランチの名前に置き換え、`#`や`&`などの特殊文字が含まれている場合は URL エンコードします。\n\n```shell\ncurl --include --header \"Authorization: Bearer YOUR-TOKEN\" \"https://api.github.com/repos/octocat/Spoon-Knife/pulls?head=HEAD-OWNER:BRANCH-NAME\"\n```\n\nリストをページングする場合は、安定した並べ替え順序を使用します。\n`sort=updated`などの一部のパラメーターは、項目が変更されるたびにリストの順序を変更します。 項目が新しい位置に移動すると、その古い位置と新しい位置の間の項目が異なるページにシフトするため、既にフェッチしたページは、 `304 Not Modified`ではなく新しいデータを返すことができます。 既定などの安定した順序では、既存のアイテムの更新がリストの順序を変更できなくなりますが、項目を追加または削除しても、エントリを他のページにシフトできます。\n\n同じデータをポーリングするたびに、同じパラメーターを使用します。 ページ サイズ、ページ番号、フィルターが異なると、異なる `etag`で異なる応答が生成されます。\n\n## エラーを無視しない\n\n繰り返し発生する`4xx`および`5xx`エラーコードを無視しないでください。 代わりに、API と正しく対話していることを確認する必要があります。 たとえば、エンドポイントが文字列を要求しているのに数値を渡している場合は、 検証エラーを受け取り、呼び出しは成功しません。 同様に、許可されていないエンドポイントまたは存在しないエンドポイントにアクセスしようとすると、`4xx` エラーが発生します。\n\nポーリング中にリソースが `404 Not Found` 応答を繰り返し返す場合は、すべてのポーリングで要求し続けないでください。 最初に、 `404` が認証または承認によって発生していないことを確認します。\nGitHubは、資格情報がアクセスを許可しない場合、一部のプライベート リソースに対する`404 Not Found`応答ではなく、`403 Forbidden`応答を返します。そのため、`404`はリソースが存在しないことを常に意味するとは限りません。 詳しくは、「[REST API のトラブルシューティング](/ja/rest/using-the-rest-api/troubleshooting-the-rest-api#404-not-found-for-an-existing-resource)」をご覧ください。 資格情報が正しいことを確認したら、もう一度確認する前にもっと長く待つか、リソースが存在すると信じる理由がある場合にのみ、もう一度確認してください。 不足しているリソースを繰り返し要求すると、レート制限が無駄になり、セカンダリ レート制限がトリガーされる可能性があります。\n\n繰り返し発生する検証エラーを意図的に無視すると、不正利用によりアプリケーションが停止されることがあります。\n\n## 参考資料\n\n* [Webhook の使用に関するベスト プラクティス](/ja/webhooks/using-webhooks/best-practices-for-using-webhooks)\n* [GitHub アプリを作成するためのベスト プラクティス](/ja/apps/creating-github-apps/about-creating-github-apps/best-practices-for-creating-a-github-app)"}