BacklogのAPIを有効活用

こんにちは。
開発チームのワイルド担当、まんだいです。

弊社では、開発ツールとしてbacklogを使っています。
backlogはgit、subversionなどのリポジトリサーバーとして、または進捗管理ツールとして、もしくは、wikiにナレッジを集約したり、課題でタスクを積んだり、まぁ色々できるツールです。

ちょこちょことAPIを使うこともあるのですが、脳みそがそろそろやばくなってきて、使い方を忘れる有様なので、コピペできそうなコードを貼り付けてみようと思います。

 

認証

OAuth2.0が提供されているんですが、正直利用していません。
バッチ的なプログラムから使う事が多いので、API Keyでのリクエスト一択な状況です。

// curlで取ってくる
curl https://xx.backlog.jp/api/v2/users/myself?apiKey=abcdefghijklmn

 

PHPで取ってくる
$response = file_get_contents('https://xxx.backlog.jp/api/v2/users/myself?apiKey=abcdefghijklmn');

 

サブドメインと、パスを変更すれば、GET系のアクセスは簡単ですね。
何より大変なのは、機能が多い上、APIがしっかり整備されているので、どのAPIを使えばいいか探すことです。

 

CRUD処理

Backlog APIはRESTfulなので、各種CRUD処理に対して明確にHTTPメソッドを定義しています。

• 情報取得なら、GET
• 情報作成なら、POST
• 情報編集なら、PUTもしくはPATCH
• 情報削除なら、DELETE

APIのエンドポイントが同じな事が多いので、HTTPメソッドを間違えると大事なデータを削除してしまう可能性もありますのでご注意ください。
編集時のPUT、PATCHの違いは、どちらかを使うという意味ではなく、APIによって受け付けるメソッドが決まっているので、Backlog APIのドキュメントを確認してください。

 

情報を取得したい時

情報を取得したい場合は、GETメソッドで送信します。

# スペース情報の取得
curl https://[subdomain].backlog.jp/api/v2/space?apiKey=[API KEY]

 

情報を作成したい時

情報を作成したい場合は、POSTメソッドで送信します。

# Wikiページの追加
curl -X POST https://[subdomain].backlog.jp/api/v2/wikis?apiKey=[API KEY] -d "projectId=xxx" -d "name=wiki_name" -d "content=hogehoge"

# 課題の新規登録
curl -X POST https://[subdomain].backlog.jp/api/v2/issues?apiKey=[API KEY] -d "projectId=xxx" -d "summary=issue_title" -d "issueTypeId=1" -d "priorityId=3"

# 種別情報の取得
# サブドメイン、プロジェクトID、API KEYを書き換え
curl https://[subdomain].backlog.jp/api/v2/projects/[xxx]/issueTypes?apiKey=[API KEY]

# 優先度一覧の取得
# サブドメイン、API KEYを書き換え
curl https://[subdomain].backlog.jp/api/v2/priorities?apiKey=[API KEY]

 

 

情報を編集したい時

情報を編集したい場合は、POST、PATCHメソッドのいずれかで送信します。
メソッドは、APIによって種類が変わるのでドキュメントを参照してください。

# プロジェクト情報の更新
# projectIdOrKeyとなっている箇所は、ProjectID、ProjectKeyのどちらでも指定可能
curl -X PATCH https://[subdomain].backlog.jp/api/v2/projects/[projectIdOrKey]?apiKey=[API KEY] -d "name=changed_name"

# お知らせの既読化
curl -X POST https://[subdomain].backlog.jp/api/v2/notifications/[notification_id]/markAsRead?apiKey=[API KEY]

# notification_idの取得
curl https://[subdomain].backlog.jp/api/v2/notifications?apiKey=[API KEY]

 

 

情報を削除したい時

情報を削除したい場合は、DELETEをメソッドを送信します。
逆に言うと、DELETEメソッドを付けなければ、削除する意思（もしくはプログラムのミス）がなければ削除される事はないでしょう。

# 課題の削除
# issueIdOrKeyの部分には、ID、Keyのどちらでも指定可能
curl -X DELETE https://[subdomain].backlog.jp/api/v2/issues/[issueIdOrKey]?apiKey=[API KEY]

 

 

APIの動作確認に便利なツール

APIの実行に便利なツールとして、Firefoxがあります。

超メジャーなブラウザアプリなので、ご存知かと思いますが、chromeばっかり使っていませんか？
BacklogのAPIをChromeで実行すると、APIの実行結果が文字化けしてしまいますが、バージョン55辺りから、文字コードの変更ができなくなったので改善する術がありません。
（恐らくHTMLではないので、エンコーディングが指定されていないため）

その点、Firefoxなら、文字化けせずに表示されますし、JSONデータを自動でパースする仕組みがいつからか導入されていて、JSONデータがとても見やすくなりました。

その他、chrome、FirefoxそれぞれRESTfulなAPI向けのアドオンや拡張機能がたくさんあるので、手に馴染むものを使うと開発は速くなります。

これらのツールはAPI開発でもよく使いますが、それでも私はテストケースも兼ねてcurlでシェルスクリプト化するクチなので、オススメのAPIブラウザ情報は提供できません・・・。

 

まとめ

簡単にまとめましたがいかがでしょうか。

タスク管理や進捗管理以外にも、WikiにJSONを貼り付けてDB代わりに使ったり、ファイル置き場として使ったり、単なる開発ツールとして以外の使い道もアイデア次第ですよね。

JSONを貼り付けて情報のやり取りをするのは、ちゃんとしたシステムでは使わない方がいいですが、個人で仕事用の小さなシェルスクリプトで作業を自動化したりする時のデータ置き場に重宝しています。
複数のサーバーをまたいで細かい処理を流す場合は、いちいちDBへの接続制限を変更したりするのも手間ですし、ポイっと置いてしまえるAPIアクセスの簡単さもあって、使いやすいと思います。

 
以上です。