はじめに
「自分のリポジトリのStar数や最終更新日を、自作のダッシュボードに表示したい」といった軽い用途であれば、GitHubアカウントを新たに作らずとも公開されているGitHub REST APIを直接叩くだけで実現できます。ただし、いくつかの仕様を知らずに実装すると、原因不明のエラーにはまりがちです。本記事では、GitHub REST APIを利用する際に最低限押さえておきたい3つのポイントを整理します。
1. 未認証アクセスにはレート制限がある
GitHub REST APIは、認証情報なし(トークンなし)でもアクセスできますが、1時間あたり60リクエストというレート制限が課されます。この制限は、リクエスト元のIPアドレス単位でカウントされます。
個人のダッシュボードで数分に1回程度データを取得する、といった低頻度の用途であれば60リクエスト/時でも十分収まりますが、頻繁にアクセスする場合や複数の情報源を組み合わせる場合はすぐに上限に達してしまいます。認証済み(トークンを使った)アクセスであれば、この上限は大幅に緩和されます。
2. User-Agentヘッダーが必須
GitHub REST APIは、User-Agentヘッダーを含まないリクエストを403 Forbiddenで拒否します。ブラウザから直接アクセスする場合は自動的に付与されるため意識しませんが、プログラムやツールから直接HTTPリクエストを組み立てる場合は、明示的に指定する必要があります。
User-Agent: your-app-name
値には自分のアプリ名やユーザー名など、リクエスト元を識別できる任意の文字列を設定するのが公式の推奨です。このヘッダーが欠けていることに気づかず「403が返ってくるのに認証は合っているはず」とハマるケースは実務でもよくあります。
3. Personal Access Token(PAT)には2種類ある
privateリポジトリの情報を取得する場合や、レート制限を緩和したい場合はPersonal Access Token(個人アクセストークン、PAT)を発行して使います。GitHubには現在2種類のPATがあります。
| 種類 | 特徴 |
|---|---|
| Classic PAT | 従来からある形式。「そのアカウントが持つ全リポジトリ」のように広いスコープで権限が付与される。有効期限を設定しなくても発行できる |
| Fine-grained PAT(推奨) | リポジトリを個別に指定して権限を付与できる、より限定的な形式。必ず有効期限を設定する必要がある。組織側で承認制にすることも可能 |
GitHub公式は、可能な限りFine-grained PATの利用を推奨しています。理由は、必要なリポジトリ・必要な権限だけに絞り込める(最小権限の原則)ことと、有効期限が必須であるため長期間放置された古いトークンが残りにくいことです。
一方で、一部のREST APIエンドポイントはClassic PATでしか利用できない、自分が所有していないpublicリポジトリへの書き込みはClassic PATでのみ可能、といった制約もあり、用途によっては使い分けが必要です。
実務上の使い分けの目安
- 自分が所有する特定のprivateリポジトリの情報だけを、ダッシュボードなどの外部ツールから参照したい → Fine-grained PATで、対象リポジトリと
Metadata: Read-onlyなど必要最小限の権限のみ付与する - 幅広いリポジトリを横断的に扱うツール(古くからあるCI連携など)で、Fine-grained PATでは動作しない特定の機能が必要 → Classic PATを検討する
まとめ
| 項目 | 内容 |
|---|---|
| 未認証時のレート制限 | 1時間あたり60リクエスト(IPアドレス単位) |
| User-Agentヘッダー | 必須。欠けていると403 Forbiddenになる |
| Classic PAT | 広いスコープ、有効期限は任意 |
| Fine-grained PAT(推奨) | リポジトリ単位で権限を絞れる、有効期限必須 |
