Postmanを使ってGraphQL経由でGitHub APIからGitHubを操作してみる
はじめに
札幌でフロントエンドエンジニアをやりつつ、札幌市のエンジニア育成事業の運営をしている n13u/NishimuraWataru です。
GitHub CLIのextension開発をしている際にGitHubにはリポジトリやissue情報を取得するためのAPIがあり、それらがGraphQLでアクセス可能なことを知りました。
extension開発をするうえでAPIの利用が必須になってくるので、いざAPIを触ってみよおうと思ったところGitHub CLIのgh api graphqlを利用した記事が多くCLIからのアクセスはやや面倒となり、Postmanを使ってみようと至った話です。
GitHub CLI extension
GitHub CLI extensionはGitHub CLIの拡張機能としてユーザー自身が独自に機能追加し、開発できる外部ライブラリです。scaffoldのツールも充実しており、Golang以外での開発もできる代物です（GitHub CLI本体はGolangで開発されています）
GitHub CLI の開発については以下記事を参考に取り組んでいます。
GitHub CLI 拡張機能の作成 - GitHub Docs
GitHub Projects(ProjectV2)にIssueやPullRequestを追加するGitHub CLIの拡張を作った
Postman について
公式の説明によると、API（この場合は特にWeb APIを指す）開発・利用のためのAPIプラットフォームとのことです。もともとはデスクトップ上でHTTPでのAPIをテストできるGUI curl的なものだった記憶ですが、現在はPostman flowsといったAPI間の接続をローコードで記述し自動化できるサービスや、Postman自体のMQTT/GraphQL対応によりプラットフォームとして進化してきているようです。
2023年12月に開催されていたPostman Conferenceでも似たような話がされていました（参加レポ書いていない...）
GitHub API を試してみる
Postmanのインストールや設定は割愛します。
Collectionを作成する
作成したQueryの保存やGraphQL Schemeの管理のためにも、PostmanでCollectionを作りましょう。
Postman Desktop 画面右上のCollectionの横にある「+」からCollectionを作成します。
モーダル一番下の青字、View more templatesをクリックします。
そうするとテンプレートが色々出てくるので左上の検索窓に「GraphQL」と入力すと、GraphQL Basicsと書かれたテンプレートが出てくるのでこれをクリックしてください。
更に開くと、右上にオレンジ色のUse Templateのボタンがあるのでこちらをクリックしてください。
画面上でGraphQLアイコンのQueries, Mutations... などができていれば問題ないです。Queriesを選択すると画面右側にリクエストが書けるようになっています。
Personal Acccess Token を取得する
GitHub API にアクセスするためには、Personal Access Tokenが必要です。
GitHub上で右上のユーザーアイコンをクリックし、出てくるナビゲーションの以下の「Settings」をクリックしてください。
いろいろな設定が出てきますが、左側サイドバーの一番下にある「Developer Settings」をクリックします。
そうすると画面左側のサイドバーが急に数が減るのでこれも一番下の「Personal access tokens」をクリック。するとメニューが開くので「Fine-grained tokens」のほうをクリックしましょう。
右上の「Generate new Token」をクリックし、赤色のアスタリスクで示された必要事項を入力します。
「Repository access」にてOnly selected Repositoriesを選択し、読み書きしたいリポジトリを選択します。今回はWataruNishimura/ferrailleを選択します。
そうすると画面下Repository Permissionsが出てくるので、「Contents」「Issues」「Pull requests」あたりのAccessをRead-onlyに変更します。
最後に画面一番下のOverviewにてPermissionsの一覧が見えるので間違いが無いか確認して、Generate token をクリック、でてきたトークンをコピーしてください
Postmanにトークンを設定
上記でコピーしたトークンを設定します。
Postman、Queriesの画面内にある「Authorizaton」タブをクリック。
TypeをBearer Tokenに設定し、token欄にコピーしたトークンを貼り付けてください。
貼付け後画面右上側にある「Save」をクリックしておきましょう。
Queryを送ってみる
まずは適当にQueryを送ってみましょう。
その前にPostmanでQueriesを選択し、{{base_url}}と書かれた部分をhttps://api.github.comに置き換えましょう。
以下は私のパブリックリポジトリにアクセスして作成日を取得するQueryです。
この場合ownerがユーザー名、nameがリポジトリ名になります。
WataruNishimura/ferraille→{name}/{owner}という仕組みです。
query {
repository(name: "ferraille", owner: "WataruNishimura") {
createdAt
}
}
このクエリをPostmanの画面右側リクエストにコピーして貼り付け、「Query」をクリックして実行します。
以下のようなレスポンスが返ってくれば成功です。
{
"data": {
"repository": {
"createdAt": "2024-02-11T11:05:08Z"
}
}
}
スキーマ情報を読み取り補完させる
Postmanでは、graphqlのスキーマを読み取り、QueryやMutationの作成時にスキーマから引数やフィールドをエディタ上で補完してくれる機能が利用可能です。（イントロスペクションと呼ばれる仕組みです）
同じく、PostmanでQueriesを開き「Schema」タブをクリックして開きます。「Using GraphQL introspection.」をクリックして完了すればOKです。
エディタ上で以下画像のようにQueryの引数やフィールドを選択できるようになっているはずです。
最後に
上記設定を終わらせれば、Mutationsを利用しissueの情報更新などもPostman経由で簡単に行うことができるようになります。良きGitHubライフを！
Discussion