Jira REST API 利用のためのコマンドラインツール「jirest」

きっかけ

• 前職では、仕事柄 Jira の REST API を使用することが多々あったのだが、そのたびに 公式マニュアル を確認して使い方を調べるのが億劫だった。
• 特にクラウド版の API はアップデートが多く、それに応じて公式マニュアルも頻繁に更新されるため、都度確認が必要になるケースが多かった。
• REST API 利用時も、いちいちスクリプトにするまでも無いケースも多く、curl などでサクッと API が叩ければ良かった。

Jira REST API 利用のためのコマンドラインツール「jirest」

以下のようなことができる、コマンドラインツール「jirest」を実装した。

• 公式マニュアル を解析し、自動で最新の API 定義を取得
• 公式マニュアル に載っている Example (curl コマンド) を、ワンコマンドで実行
• 公式マニュアル の Example をベースに、ユーザーオリジナルなコマンド実行用テンプレートも定義可能

インストール

docker image として配布 しているため、以下の手順のみで利用可能。

1. $HOME 配下に、jirest データ用ディレクトリ作成

    $ mkdir $HOME/.jirest
   

2. .bashrc に、以下の一行を追加

    alias jirest='docker run -it --rm -v $HOME/.jirest:/root/jirest/data okamotoyuki/jirest'
   

使い方

Jira Cloud インスタンス・ユーザー情報設定

以下のコマンドで、Jira Cloud のインスタンス・ユーザー情報を設定する。

$ jirest init

認証のためのトークンは、API トークン に記載の方法で生成可能。

API 情報取得

以下のコマンドで、任意の API 情報を取得する。

$ jirest describe

API 実行用 curl コマンド生成

以下のコマンドで、任意の API 実行用の curl コマンドを生成する。(即時実行はしない。)

$ jirest dryrun

ユーザー定義の API 実行用テンプレートが存在する場合にはそちらを利用してコマンドを生成、存在しない場合には 公式マニュアル 上の Example を元にコマンドを生成する。

API 実行にパラメータを要する場合には、ターミナル上でそれらの値の入力が求められる。

API 実行

以下のコマンドで、任意の API を即時実行する。

$ jirest exec

ユーザー定義の API 実行用テンプレートが存在する場合にはそちらを利用して生成したコマンドを実行、存在しない場合には 公式マニュアル 上の Example を元に生成したコマンドを実行する。

API 実行にパラメータを要する場合には、ターミナル上でそれらの値の入力が求められる。

API 実行用テンプレートの定義

以下のコマンドで、任意の API 実行用のテンプレートを定義する。

$ jirest edit

テンプレートには、{paramName} の形式で API 実行に必要なパラメータを埋め込むことができる。 使用可能なパラメータは、テンプレート編集画面上部にコメントとして表示される。 以下に、テンプレートの例を示す。

#       projectIdOrKey (string):
#               The project ID or project key (case sensitive).
#       id (integer):
#               The ID of the project role. Use Get all project roles to get a list of project role IDs.

curl --request POST \
  --url '/rest/api/3/project/{projectIdOrKey}/role/{id}' \
  --user '[email protected]:<api_token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "group": [
    "jira-developers"
  ]
}'

API 実行用テンプレートの削除

以下のコマンドで、ユーザーが定義した任意の API 実行用のテンプレートを削除する。

$ jirest revert

API 定義の更新

以下のコマンドで、公式マニュアル に基づいて API 定義を最新のものに更新する。

$ jirest update

API 定義のロールバック

jirest update にて API 定義を更新したことによって、何らかの問題が生じた場合には、以下のコマンドにて API 定義を安定版にロールバックすることができる。

$ jirest reset

おわりに

バグ・機能リクエストは GitHub issues で受け付けています。 もちろんプルリクエストも大歓迎です。