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

ポーリングを回避する

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

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

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

同時にリクウェストする事を避けてください。

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

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

単一のユーザーまたはクライアント ID で多数の POST、PATCH、PUT、DELETE 要求を行う場合は、各要求の間を少なくとも 1 秒空けてください。これは、セカンダリレート制限を回避するのに役立ちます。

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

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

retry-after 応答ヘッダーが存在する場合は、その秒数が経過するまで要求を再試行しないでください。
x-ratelimit-remaining ヘッダーが 0 の場合、x-ratelimit-reset ヘッダーで指定された時刻 (UTC エポック秒数)が過ぎるまで要求を再試行しないでください。 x-ratelimit-reset ヘッダーは UTC エポック秒単位です。
それ以外の場合は、少なくとも 1 分間待ってから再試行します。セカンダリレート制限の要求が継続して失敗する場合は、再試行の間に指数関数的に増加する時間を待ち、特定の回数の再試行の後にエラーをスローします。

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

リダイレクトへの追従

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

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

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

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

多くの 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 受け取ります。 Authorization ヘッダーを使って適切に認可された状態で 304 応答が返された場合、条件付き要求を行っても、プライマリレート制限にはカウントされません。

たとえば、前の要求でヘッダー値が返された etag 場合、将来の 644b5b0155e6404a9cc4bd9d8b1ae730要求でヘッダーを 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 エラーが発生します。

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

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

この記事の内容