GitHub API v4 を適当な知識で使ってみる #GitHub

ドキュメント

GraphQL クライアントの選択

GraphQL API を呼ぶためのクライアントは色々ある。

GitHub API 専用の GitHub GraphQL API Explorer を使うのが手っ取り早いかもしれないが、ここでは Altair (アルタイル) を使ってみる。

Altair の起動

サイトから Altair の Chrome extension をインストールして起動すると、以下のような画面が表示されるので、エンドポイントに以下を入力し、おもむろに「Send Request」してみる。当然、認証エラーになる。

GitHub https://api.github.com/graphql
GitHub Enterprise の場合 http(s)://[hostname]/api/graphql

認証

GitHub にログインし、Settings > Developer Settings > Personal access tokens から「Generate new token」をおこなう。「Scopes」には API 呼び出しに必要な権限を選択する。ここで設定した権限に不足がある場合は API 実行時に認可エラーになるが、あとから設定変更もできるのでまずは適当に。とりあえず変なことはできないよう Read 系のみにするのが無難かも。

アクセストークンは一度しか表示されないので、メモっておく。

生成したアクセストークンを Altair に設定する。画面左のナビゲーションにある「Set Headers」をクリックし、以下のように入力する。これで、以降のリクエストすべてに設定したヘッダが送信される。

Header key	Header value
Authorization	bearer (アクセストークン)

API ドキュメントの参照

「Send Request」の左にある「Docs」をクリックし、さらにその左の「Reload Docs」をクリックする。認証が正常に通れば API ドキュメントが表示される。「Query」は読み込み API、「Mutation」は書き込み API と分かれているので、まずは「Query」をクリックする。API 一覧が表示されるので、好きなものをホバーして、表示される「ADD QUERY」ボタンをクリックする。これで、その API を呼ぶクエリの雛形が、クエリペインに設定される。

たとえば user のクエリは以下のようになる。


query{
  user(login: ______){
    anyPinnableItems(type: ______)
    avatarUrl(size: ______)
    bio
    bioHTML
    ...
  }
}

まずはざっくりと以下のような認識でOK。埋める必要のあるところは「______」になっていてそのままではエラーになるので、条件を埋めたり、取得する必要のないものは削除したりして、エラーが消えたら「Send Request」をおこなう。

query {
    欲しいもの(条件) {
        欲しいもの
    }
}

実行例

取れた。

まとめ

GraphQL では API 仕様が実装に直結した形で取得できるため、クエリを自動生成する仕組みもクライアントで実装しやすく、ドキュメントとにらめっこしなくても適当に呼び出してみることができる。GraphQL として、読み取り専用の「Query」と、書き込みが発生する「Mutation」が明確に分かれているので、Query だけであればいくらでも試してみれば良いと思う。GitHub の API ドキュメントは別途あるのだが、正直分かりづらいので、強力なツールを活用して理解していきましょう!