GithubAPIについて色々とまとめてみた #GitHub

GithubにはAPIがあり、これを使えばGithub上での色々な操作が可能になります。

2016/01/28現在、GithubAPIのVersionはv3であり、これを基にまとめていきます。

GithubAPIを使えば何が出来るの？

さて、APIAPIと言っておりますが実際にGithubAPIを使えば何が出来るのでしょうか？
ザッと出来ることを一部以下に書き出してみます。

NotificationsやFeedsの取得
Gistの生成・更新・取得・削除
Issuesの生成・更新・取得・削除
Organizationsの一覧やメンバーの取得
Pull Requestの生成・更新・取得・削除
Repositoryの生成・更新・取得・削除

などなど。
これはほんの一部なのですが、大方このようなことはAPIを使うことで実現できます。

どうやったらGithubAPIを使えるの？

一部のAPIは何も考慮しなくとも特定のURLにアクセスすることで結果を取得できます。

e.g.

curl -i https://api.github.com/users/defunkt

HTTP/1.1 200 OK
Server: GitHub.com
Date: Sun, 11 Nov 2012 18:43:28 GMT
Content-Type: application/json; charset=utf-8
Connection: keep-alive
Status: 200 OK
ETag: "bfd85cbf23ac0b0c8a29bee02e7117c6"
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 57
X-RateLimit-Reset: 1352660008
X-GitHub-Media-Type: github.v3
Vary: Accept
Cache-Control: public, max-age=60, s-maxage=60
X-Content-Type-Options: nosniff
Content-Length: 692
Last-Modified: Tue, 30 Oct 2012 18:58:42 GMT

{
  "login": "defunkt",
  "id": 2,
  "url": "https://api.github.com/users/defunkt",
  "html_url": "https://github.com/defunkt",
  ...
}

しかし、このままでは以下の制限を受けることになります。

API制限として１時間に60回しかAPIを実行できない
一部のAPIしか使用できない

なので、APIをフルに使えるように認証を行います。

認証って？

APIをフルに使うために認証が必要と先ほど説明しましたが、認証方法には３つの方法があります。

基本認証

curl -u "username" https://api.github.com
Enter host password for user 'username':

OAuth2認証（ヘッダー送信ver）

curl -H "Authorization: token OAUTH-TOKEN" https://api.github.com

OAuth2認証（パラメータ送信ver）

curl https://api.github.com/?access_token=OAUTH-TOKEN

基本的にはこの３つのどれかを用いてAPIを実行することになります。
ただし、Githubとしては基本認証よりもOAuth2認証を勧めています。

参考：https://developer.github.com/v3/auth/

認証した場合のAPI制限は以下のように緩和されます。

１時間に5000回、APIを実行できる
全てのAPIが実行できるようになる

ただし、OAuth2認証の場合はscopeの設定によっては実行できないAPIがあります。（scopeについては後ほど説明）

OAuth2認証はどうやって認証させるの？

ここからはOAuth2認証を使ったAPIの実行を説明していきます。

まずは、OAuth2認証の認証方法ですが以下の３種類があります。

Webアプリケーションを使った認証
Webアプリケーションを使わない認証
Personalアクセストークンを使った認証

Webアプリケーションを使った認証

この認証方法は、Githubアカウントを使ったログインでよく見かけているかもしれません。

この画面のように、ブラウザ上で認証させる方式ですね。

認証は以下の流れで行われます。
別途、認証用のGithubアプリケーション作成と、認証後のコールバック処理用のサーバが必要になりますのでご注意ください。

認証用URLにアクセスさせる
「Authorize application」を押下してもらう
指定したコールバックURLに各種パラメータが返ってくる
パラメータ内のcodeを使いアクセストークンを取得する

これ以後は取得したアクセストークンを用いて、APIを実行する形になります。

この認証方法については@ngs氏のこちらの記事に詳しく書かれています。
GitHub API v3 でリポジトリを作成して、ファイルをコミットする

Webアプリケーションを使わない認証

先ほどの認証とは逆にWebアプリケーションを使わない認証方法もあります。

こちらはとても簡潔でパラメータとともにcurlでPOSTすればいいだけです。
認証用のGithubアプリケーションの作成も必須ではありません。

e.g.

curl -u syossan27 -X POST -d '{"note":"test"}' https://api.github.com/authorizations

パラメータ名	型	説明
scopes	array	認証に伴うGithub操作権限の付与設定
note	string	必須パラメータ：この認証がどういった理由で行われるかの説明。アプリケーションと紐付けない場合は、ユニークであることが条件
note_url	string	別途詳しいnoteが書かれている場合のURL
client_id	string	紐付けるGithubアプリケーションのクライアントID
client_secret	string	紐付けるGithubアプリケーションのクライアントシークレット
fingerprint	string	一人のユーザに対して複数のトークンを生成したい場合に、それぞれのトークンを区別するために使われる値

Githubアプリケーションやサーバの準備無しに使うことが出来るため便利ではあるが、ユーザからは非常に怪しい認証に見えてしまう（ユーザ名とパスワードを入力するので）ため、はWebアプリケーションを使った認証の方がメジャーに使われている。

またユーザが二段階認証を使用している場合、とても面倒な方法を取らないといけないため、そういった意味でもWebアプリケーションを使った認証をGithubは勧めています。

参考：https://developer.github.com/v3/auth/#working-with-two-factor-authentication

Personalアクセストークンを使った認証

GithubにはPersonalアクセストークンというアクセストークンを生成することができます。
OAuth認証で得られたアクセストークンとほとんど違いは無いのですが、アクセストークンを自分で管理出来るという利点と、一部のscopeでの動きが違うという注意点があります。

GithubのSettingの左メニューに Personal access tokens があり、
ここからPersonalアクセストークン画面へ飛べます。

割り当てる権限を設定し、 Generate Button を押下することでPersonalアクセストークンを生成することができます。

参考：Creating an access token for command-line use

OAuth2認証で割り当てられる権限（scope）ってどんなものがあるの？

OAuth2認証ではアプリケーションに対してユーザへの操作権限をそれぞれ割り当てる必要がある。

権限は以下のように分かれている。

権限名	説明
(何も権限を割り当てない場合)	パブリック情報の読み取りのみ可能
user	ユーザ情報の読み取り/書き込みが可能この権限はuser:email・user:followを包括する
user:email	ユーザのメールアドレスのみ読み取り可能
user:follow	他ユーザのフォロー、アンフォローが可能
public_repo	パブリックリポジトリのコード、コミット、コラボレーター、デプロイメントの読み取り/書き込みが可能。公開リポジトリへスターを付けることも可能に。
repo	プライベートリポジトリのコード、コミット、コラボレーター、デプロイメントの読み取り/書き込みが可能。
repo_deployment	パブリックリポジトリ、プライベートリポジトリのデプロイメントの操作が可能。このscopeはコードへのアクセスをさせずに、他のユーザ・サービスにデプロイメント操作権限を与えることができる。
repo:status	パブリックリポジトリ、プライベートリポジトリのコミットの読み取り/書き込みが可能。このscopeはコードへのアクセスをさせずに、他のユーザ・サービスにコミット操作権限を与えることができる。
delete_repo	adminであるリポジトリを削除可能。
notifications	ユーザへのお知らせを取得することが可能。`repo`はnotifications権限も与えます。
gist	Gistへの書き込みが可能
read:repo_hook	パブリックリポジトリ、プライベートリポジトリのhookの読み取り/pingが可能
write:repo_hook	パブリックリポジトリ、プライベートリポジトリのhookの読み取り/書き込み/pingが可能
admin:repo_hook	パブリックリポジトリ、プライベートリポジトリのhookの読み取り/書き込み/削除/pingが可能
admin:org_hook	Organizationのhookの読み取り/書き込み/削除/pingが可能注意：OAuth2認証で発行されたアクセストークンではOAuthアプリケーションが作成したOrganizationのfookに対して操作が可能になり、Personalアクセストークンの場合はユーザが作成したOrganizationのfookに対して操作が可能になります。
read:org	Organization、teams、membershipの読み取りが可能
write:org	Organization、membershipの公開・非公開の操作が可能
admin:org	Organization、teams、membershipの全操作が可能
read:public_key	PublicKeyの読み取りが可能
write:public_key	PublicKeyの読み取り/書き込みが可能
admin:public_key	PublicKeyの読み取り/書き込み/削除が可能

勿論ではあるが、「あなたの全ての操作権限をこのアプリケーションに割り当てますよ」となると嫌がるユーザもいるので適切な権限の割り当てが必要になります。

GithubAPIについて色々とまとめてみた