Atlassian SDKでREST API Browserを使ってみます #Confluence

今回とりあげること

今回は、このREST API Browserの起動と利用法用についての紹介になります。

どういうもの？

ConfluenceやJIRAで、ちょっとしたことをコマンドラインで操作したりしたい場合があります。
AtlassianのSDKを利用すると、開発用のConfluenceやJIRAのインスタンス起動ができます。

この環境には、クイックデプロイやデバッグといった、開発支援のための機能が付いています。
REST API Browserもその１つで、ブラウザ上からRESTのコマンドのAPIを一覧表示してくれたり、さらにはパラメータを変更してのデータ送受信のテストを行うことができます。

従来のRemote APIであるSoapやXML-RPCはちょっと敷居が高いのですが、バージョンアップに伴い、RESTで実行できる処理が増えているので、こんな処理を自動化したいな...と思ったら、まずはREST API Browserを使ってみると良いかと思います。

特に、HTTPのリクエスト／レスポンスの生データも画面で確認できるので、curlなどのUnixコマンドでAPIを利用する場合にも、かなり参考になるかと思います。
ただし、本家に精確な情報が載っていますので、英語が苦でない方は、ぜひそちらをご覧下さいませ。

Using the REST API Browser (Atlassian Developers Document)

必要なものは？

Atlassian SDKが必要です。SDKを使って、ConfluenceやJIRAのローカルの開発用サーバを起動すると、それに伴い利用できるようになります。

なお、「SDKを使っての確認まではしたくない、手っ取り早くどんなものか確認したい」という場合は、クラウド版のREST API Browserとして下記の２つがAtlassianから提供されていますので、こちらもどうぞ。

JIRA Cloud版: https://bunjil.jira-dev.com/plugins/servlet/restbrowser
Confluence Cloud版: https://bunjil.jira-dev.com/wiki/plugins/servlet/restbrowser

※実際のデータが無ければうまくレスポンスは返ってきませんが、API一覧と送信テストは可能です。

起動方法

SDKのatlas-runコマンドや、atlas-debugで対象のアプリケーションを起動すればOKです。
以下は、Stashの例です

### Confluenceの場合
## % atlas-run-standalone --product confluence

## 以下はStashの例
% atlas-run-standalone --product stash
Executing: /usr/share/atlassian-plugin-sdk-xxx/apache-maven-xxx/bin/mvn com.atlassian.maven.plugins:maven-amps-plugin:xxx:run-standalone -gs /usr/share/atlassian-plugin-sdk-xxx/apache-maven-xxx/conf/settings.xml -Dproduct='stash'
[INFO] Scanning for projects...
[INFO] 

...[中略]...

[INFO] [talledLocalContainer] Tomcat 7.x started on port [7990]
[INFO] stash started successfully in 243s at http://localhost:7990/stash
[INFO] Type Ctrl-D to shutdown gracefully
[INFO] Type Ctrl-C to exit

ビルド＆サーバ起動後、メッセージに出て来るURLにアクセスします。

まずは一般的なアカウント（デフォルトでadmin)でログインします
画面右下の、ツールボックスアイコンをクリックすると、開発用のメニューが出て来ます
REST API Browserを選びます

REST API Browserのサーブレットが呼ばれ、APIドキュメント一覧と、テスト用のフォームが表示されます。

スクリーンショット

POSTやPUT, DELETEのテストも画面から実施できます。
以下は、引き続きStashの例です。

POSTメソッドの実施

所定のプロジェクトに、リポジトリを追加するテストです。
画面にはサンプルのリクエストパラメータ（JSON) が設定されているので、あとはどのプロジェクトかの指定をして、ボタンを送信します。

※ Request Bodyもデフォルトのデータだけではなく、画面からの修正／変更ができます。

うまくいくと、通常のStashのプロジェクトのリポジトリ一覧に、上記で作成したリポジトリが追加されます。

こちらは、Confluenceの場合。
まだそんなにREST APIとして利用できるものは多く有りません。

コマンドライン (curl)から

REST APIが有効になっていれば、あとはAPIドキュメントに従って他の言語やクライアントからの呼び出しができます。
以下は、curlからREST APIにアクセスしてみた例です。

動作: 指定のプロジェクトに存在するリポジトリの情報を取得する
- GETメソッドでURLの一部にパラメータを埋め込む
URLパターン: api/1.0/projects/{projectKey}/repos/{repositorySlug}


## リポジトリ情報の取得
%  curl --user admin:パスワード http://localhost:7990/stash/rest/api/1.0/projects/PROJECT_1/repos/my-repo
{"slug":"my-repo","id":11,"name":"My repo","scmId":"git","state":"AVAILABLE","statusMessage":"Available","forkable":true,"project":{"key":"PROJECT_1","id":1,"name":"Project 1","description":"Default configuration project #1","public":false,"type":"NORMAL","link":{"url":"/projects/PROJECT_1","rel":"self"},"links":{"self":[{"href":"http://localhost:7990/stash/projects/PROJECT_1"}]}},"public":false,"link":{"url":"/projects/PROJECT_1/repos/my-repo/browse","rel":"self"},"cloneUrl":"http://admin@localhost:7990/stash/scm/project_1/my-repo.git","links":{"clone":[{"href":"http://admin@localhost:7990/stash/scm/project_1/my-repo.git","name":"http"},{"href":"ssh://git@localhost:7999/project_1/my-repo.git","name":"ssh"}],"self":[{"href":"http://localhost:7990/stash/projects/PROJECT_1/repos/my-repo/browse"}]}}

次に、削除のパターン。

動作: 指定のプロジェクトに存在するリポジトリを削除する
- DELETEメソッドでURLの一部にパラメータを埋め込む
URLパターン: api/1.0/projects/{projectKey}/repos/{repositorySlug}

## 削除実施
%  curl --user admin:パスワード -X DELETE http://localhost:7990/stash/rest/api/1.0/projects/PROJECT_1/repos/my-repo
{"context":null,"message":"リポジトリは削除予定です。","exceptionName":null}% 

## 確認
%  curl --user admin:パスワード http://localhost:7990/stash/rest/api/1.0/projects/PROJECT_1/repos/my-repo
{"errors":[{"context":null,"message":"リポジトリPROJECT_1/my-repoは存在しません。","exceptionName":"com.atlassian.stash.exception.NoSuchRepositoryException"}]}

うまく消えました。

まとめ／注意点など

以上、簡単ですが、REST API Browserの紹介でした。

Using the REST API Browser の末尾にも書かれている通り、Javaで実装されたプラグインでREST APIを持っているものがあれば、REST API Browserに自動でAPI情報が表示されるようになる、とのことです。

残念ながら、わたしはそこまでの開発ができないので、この辺は未確認です。

注意点

SDKで各プロダクトを起動すると、デフォルトでは各プロダクトの最新のバージョンが起動します。
ただし、実際の環境（本番環境）ではバージョンが少し古いことのほうが多いので、利用できないAPIがあったりしますので、ご注意を。

また、API一覧には出てきていないけれど、ブラウザのログから「なんとなく利用可能そう」なAPI、リクエストのパターンを見つけることもあります。この場合、バージョンが上がったりすると、逆に使えなくなる可能性があるので、ご注意を。