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


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アカウントを使ったログインでよく見かけているかもしれません。

![スクリーンショット_2016-01-28_12_06_53.png](https://qiita-image-store.s3.amazonaws.com/0/39382/8917b345-d251-26aa-25a0-0a5ba313c24e.png "スクリーンショット_2016-01-28_12_06_53.png")

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

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

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

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

この認証方法については@ngs氏のこちらの記事に詳しく書かれています。
[GitHub API v3 でリポジトリを作成して、ファイルをコミットする](http://qiita.com/ngs/items/34e51186a485c705ffdb)

### 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アクセストークン画面へ飛べます。
![personal1.png](https://qiita-image-store.s3.amazonaws.com/0/39382/c5713820-ca95-d6d4-9790-462f625e4d05.png "personal1.png")

割り当てる権限を設定し、 __Generate Button__ を押下することでPersonalアクセストークンを生成することができます。
![personal2.png](https://qiita-image-store.s3.amazonaws.com/0/39382/c58878ad-14f9-f787-e713-a37ac03fa0d8.png "personal2.png")

参考：[Creating an access token for command-line use](https://help.github.com/articles/creating-an-access-token-for-command-line-use/)

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

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

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

| 権限名                    | 説明                   |
|--------------------------|:----------------------|
| (何も権限を割り当てない場合) | パブリック情報の読み取りのみ可能 |
| user                     | ユーザ情報の読み取り/書き込みが可能<br>この権限はuser:email・user:followを包括する|
| user:email               | ユーザのメールアドレスのみ読み取り可能 |
| user:follow              | 他ユーザのフォロー、アンフォローが可能 |
| public_repo              | パブリックリポジトリのコード、コミット、コラボレーター、デプロイメントの読み取り/書き込みが可能。<br>公開リポジトリへスターを付けることも可能に。
| 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が可能<br>__注意：__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リファレンス（執筆途中）](http://qiita.com/syossan27/items/85a5b7255cb901b61a23)