何をするのか
Githubレポジトリの情報を取得するためにPOSTMANというプラットフォームで実行。
POSTMANで「GraphQL API v4」を使い、クエリを叩き、repository情報の取得をします。
この投稿では、
- APIをPOSTMANに追加
- 簡単なqueryを叩く
までを記述していきます。
Postmanとは
公式サイトはこちらです。
POSTMANは、API開発のための総合的な環境です。
今回は、API自作の目的はなくGraphQL API v4を使ったGithub情報取得を目的としていますので、API直感的に利用できる環境と言うイメージだと思います。
やってみよー
では実際に進めていきます。POSTMANのDocumentではインストから様々なAPIの操作方法についての記載もあるので、そちらもチェックしてみてください。
環境
OS --- macOS Catalina version 10.15.5
POSTMAN --- Postman v7.25.2
API --- GraphQL API v4
前提準備
- POSTMANのインストール（POSTMAN Download Pageからできます）
- GithubAPIの認証・OAuth token(アクセストークン)の取得（こちらのGithubDocsを参考に）
1. POSTMANにAPIを登録
まずは、POSTMANにGraphQLのAPIを追加します。
Schemaのダウンロード
こちらから、GraphQLのPublic Schemaをダウンロードできます。
POSTMANに新しいAPIを追加
POSTMANを開くと左上にこのような表示があるので、右の「APIs」を選択、「New API」をクリックして、新しいAPIを追加します。
すると、このようなウィンドウが開くので、APIの名前、バージョン任意で入れます。
Schema type は GraphQL
Schema format は GraphQL SDL
を選択して、先程ダウンロードした "schema.public.graphql" をアップロードします。
できたら、Create APIで作成します。
これで、APIの登録は完了です。
2. queryを叩く
次にクエリを作っていきます。
新しいリクエストを作成
⌘+Tで新しいタブで無題のリクエストが作成されます。
リクエストの詳細を設定
次にリクエストの詳細を設定していきます。
- リクエストのタイプをデフォルトのGETから、POSTに変更します。
- URLは「https://api.github.com/graphql 」と入力します。
- Authorizationのタブを選択し、認証Typeを選びます（私はOAuth2.0にします）。
必要な認証情報を入力したら、設定完了です。
クエリを叩く
いよいよ、クエリを入力していきます。
Bodyタブを選択し、タイプはGraphQLを選択します。
「QUERY」という欄がクエリを書くところ、右側の「GRAPHQL VARIABLES」の欄にはJSON形式で変数を定義するところです。
レスポンスは、JSON形式で返ってきます。
（今回は、変数の使い方について触れないので、こちらを参考にしてください。）
自分の情報 user()
{
user(login: "\任意のユーザー名\") {
name
}
}
レスポンスは省略しますが、自分のGithubの表示名が返ってきます。
オープンアカウントの情報 repositoryOwner()
「repositoryOwner()」で、任意のアカウントの情報を取得できます。
ここでは、レポジトリの総数を取得するクエリです。
{
repositoryOwner (login: "facebook") {
repositories {
totalCount
}
}
}
レスポンスは以下です。
{
"data": {
"repositoryOwner": {
"repositories": {
"totalCount": 127
}
}
}
}
オープンレポジトリの情報 repository()
「repository()」でオープンレポジトリであればレポジトリ情報が取得できます。
「owner:"", name:""」と書くと省略できるので、アカウント情報は必要なくて特定のレポジトリ情報だけが必要な場合は、おすすめです。
ここでは、forkの総数・issueの総数・stargazerの総数・watcherの総数・pullRequestの総数・labelsの総数・milestoneの総数を取得するクエリです。
{
repository(owner:"facebook",name:"react"){
forks {
totalCount
}
issues {
totalCount
}
stargazers {
totalCount
}
watchers {
totalCount
}
pullRequests {
totalCount
}
labels{
totalCount
}
milestones{
totalCount
}
}
}
レスポンスは以下です。
{
"data": {
"repository": {
"forks": {
"totalCount": 29096
},
"issues": {
"totalCount": 9486
},
"stargazers": {
"totalCount": 154618
},
"watchers": {
"totalCount": 6684
},
"pullRequests": {
"totalCount": 9968
},
"labels": {
"totalCount": 59
},
"milestones": {
"totalCount": 39
}
}
}
}
一つひとつのissueの内容を取得
issueに限らず、以下の方法でそれぞれの情報を取得できます。
「(first: ## )」では、「はじめの##個」という指定ができます。APIの使用で最大100個までが取得可能です。
"last: ##", "after: '$$$'", など、いろんな制約を設けられます。
今回は、はじめの10個のissueについて、
- タイトル
- issueID
- closedされているか（Boolean）
- createdAt（timestamp iso 8601 "YYYY-MM-DDTHH:MM:SSZ")
- closedAt（timestamp iso 8601 "YYYY-MM-DDTHH:MM:SSZ")
を取得するクエリです。
{
repository(owner:"facebook",name:"react"){
issues(first:10) {
totalCount
edges {
node {
title
number
closed
createdAt
closedAt
}
}
}
}
}
レスポンスは以下です。
{
"data": {
"repository": {
"issues": {
"totalCount": 9486,
"edges": [
{
"node": {
"title": "Can't require() react-tools module",
"number": 10,
"closed": true,
"createdAt": "2013-05-30T03:46:02Z",
"closedAt": "2013-05-30T12:14:18Z"
}
},
{
"node": {
"title": "Write tests for react-tools module",
"number": 12,
"closed": true,
"createdAt": "2013-05-30T04:32:10Z",
"closedAt": "2013-05-31T14:39:43Z"
}
},
{
"node": {
"title": "must adding comments for JSX?",
"number": 16,
"closed": true,
"createdAt": "2013-05-30T12:46:11Z",
"closedAt": "2013-07-21T17:08:03Z"
}
},
{
"node": {
"title": "Small update to Bower command",
"number": 21,
"closed": true,
"createdAt": "2013-05-30T16:01:55Z",
"closedAt": "2013-05-30T18:54:41Z"
}
},
{
"node": {
"title": "Fix docs Rake \"update_version\" command to strip trailing spaces",
"number": 24,
"closed": true,
"createdAt": "2013-05-30T18:09:21Z",
"closedAt": "2013-07-21T17:08:47Z"
}
},
{
"node": {
"title": "Make valid npm release",
"number": 26,
"closed": true,
"createdAt": "2013-05-30T18:55:49Z",
"closedAt": "2013-05-30T19:23:46Z"
}
},
{
"node": {
"title": "React in RequireJS ?",
"number": 28,
"closed": true,
"createdAt": "2013-05-30T20:51:32Z",
"closedAt": "2014-01-06T21:20:52Z"
}
},
{
"node": {
"title": "Docs don't even mention reconciliation!",
"number": 37,
"closed": true,
"createdAt": "2013-06-01T20:01:11Z",
"closedAt": "2013-07-21T17:05:49Z"
}
},
{
"node": {
"title": "Is es5-sham required for IE8?",
"number": 39,
"closed": true,
"createdAt": "2013-06-02T09:08:10Z",
"closedAt": "2013-07-24T20:12:30Z"
}
},
{
"node": {
"title": "Uncaught SyntaxError: Unexpected token < ",
"number": 40,
"closed": true,
"createdAt": "2013-06-02T13:27:44Z",
"closedAt": "2013-06-03T14:05:11Z"
}
}
]
}
}
}
}
3.終わりに
POSTMANは、取ってきたい情報をが明確にあったり、GraphQLの表記確認などで非常に役に立ちます。
ただ、大量な情報収集には向いていないかと思います。
GraphQLはGithubAPIの中でも、詳細の情報が収集可能なのでデータ分析の収集ステップには適していると思います。