ここ数日、ダッシュボードを開発する必要があり、Trello と GitHub の API に触れる機会がありました。そのときの情報を整理したので、GitHub API を使う必要がある方は、ぜひこの記事を読んでみてください。GitHub も RESTful HTTP API の形式を採用しており、開発はとても簡単です。HTTP API の連携経験がある人なら、特にすぐに使いこなせるでしょう。私が見てきた中でも、GitHub API はトップクラスに API フレンドリーだと思います。ドキュメントがわかりやすいだけでなく、API も豊富なパラメータを用意しています。さらに将来は GraphQL API も提供される予定で、とても楽しみです！

GraphQL API に興味がある場合は、Early Access Program から申請できます。

初めて HTTP API を試す場合は、Quick Started を読んでください。

各プログラミング言語には、公式・非公式の SDK が用意されています。GitHub API Libraries を参照してください。もちろん、HTTP API を直接呼び出しても問題ありません。

GitHub API でできることも多くあります。Commit、Pull Request、Issue、User、Repo のいずれも操作でき、パラメータも非常に細かく指定できます。たとえば私は「最新でマージされた PR を 5 件取得する」必要がありましたが、GitHub が提供しているソートのフィールド（updated_at、created_at など）とソート方向（ASC、DESC）のパラメータのおかげで、簡単に解決できました。

開発ドキュメントの上部（下の画像を参照）には多くの情報がありますが、この設計は見落とされやすいことがあります。

GitHub は API のほかに Webhook も提供しています。API タブには Webhook API がありますが、上部には Webhook タブもあります。実はこの 2 つは別物です。Webhook API は Webhook の作成、照会、削除を行うためのものです。Webhook 自体の書き方については、上部の Webhook タブを確認する必要があります。Webhook を設定したい場合は、リポジトリの Settings ページから直接設定するか、Webhook API を使って作成できます。

開発を始める前に、Overview を最後まで読むことをおすすめします。役立つ情報がたくさん含まれています。自分で RESTful API を開発する場合にも、GitHub API の Overview を読んで、重要または興味深い部分を抜き出して紹介します。

Overview には Rate Limit についても書かれています。多くの開発者が見落としがちな点ですが、非常に重要です。奇妙なバグが Rate Limit に関係していることもあります。最近は、AWS や Google API に限らず、どのサードパーティのサービスを使う前にも「制限」の部分を確認する習慣をつけています。呼び出しすぎてデータを失ったり、ブロックされたりしないためです。興味深いことに、GitHub は HTTP ヘッダーに Rate Limit の情報を含めています。上限、残りの利用量、リセットまでの時間が含まれているため、プログラムの中で判断に使えます。

返されるデータのうち、時刻に関する項目はすべて GMT+0 です。適切なタイムゾーンに変換することを忘れないでください。たとえば、コミット数の時系列の変化をグラフにしたかったのですが、タイムゾーンの誤りのせいで、描画された 1 日ごとのコミット数が想定と異なっていました。

また、GitHub API は CORS と JSONP に対応しています。

認証については、OAuth は必ず対応する必要がありますが、用途に応じて GitHub はほかの方法も提供しているので、OAuth を避け続けることもできます（冗談です）。

  • ユーザーとやり取りして、ユーザーの GitHub データにアクセスする必要がある場合：素直に OAuth を使いましょう。ドキュメントは GitHub API OAuth を参照してください。
  • バックエンドで動作し、対話のない処理、たとえば会社のプロジェクトをこっそり自動バックアップする小さなプログラムの場合：Personal Access Token を使えます。有効期限がなく、プライベートリポジトリや組織のリポジトリにもアクセスできます。GitHub の Settings からユーザーが操作するだけで取得でき、プログラムに直接入れれば動作します。詳しくは Github API Basic Authentication を参照してください。
curl -u username:token https://api.github.com/user
もちろん、キーを使わずにアカウントとパスワードで認証することもできます。ただ、開発者としてそれを本当にやる勇気がありますか？ 少なくとも Personal Access Token を使うことをおすすめします。万一トークンが漏洩しても、取り消せば解決しますし、Personal Access Token では権限の管理もできます。

Personal Access Token で認証すれば、二要素認証の問題も解決できます。

Personal Access Token の権限を管理できます。

最後に、ドキュメントには返されるデータ件数の制限方法が特に書かれていません。実はその機能は、ページネーションという別の名前で提供されています。per_page パラメータを使えば、件数を制限するのと同じ効果が得られます。

  • per_page： N 件ごとに 1 ページに分割
  • page： M ページ目を取得
https://api.github.com/repo/linroex/hello/commits?per_page=10&page=1
GitHub は、まさにエンジニアに寄り添うサービスの会社だと言わざるを得ません。API がフレンドリーなだけでなく、ドキュメントも詳細で読みやすく、全体の設計の流れも良いです。Auth すら見つからなかった Trello API や、一覧にはある機能なのに使えなかった Facebook Graph API とは大違いです。GitHub、大好き！