こんにちは。CData Software Japan リードエンジニアの杉本@Postman愛好家です！
前回、backlog APIの使い方なる記事を公開しました。
www.cdatablog.jp
記事では Postmanを使って backlog API の使い方を解説しているんですが、backlog APIってものすごく機能が多いじゃないですか！
（150種類のAPIを網羅したExcelファイル）
しかも最近、私の会社でUSチームやアルバニア・インドチームに backlog の APIをシェアしていたりしたので、もっと手軽に同じAPIを試せるようにしたいな！ と考えたのです。
そこで、backlog の全リソース X HTTPメソッドを網羅した Postman Collection を作成してみました！ 本来の目的は社内での共有だったのですが、とても便利な感じに仕上がったので、Githubで公開までしてみました！
github.com
（ちなみに日本語版と英語版があります）
この記事では、その私が作成した backlog Postman Collection の使い方を解説します！
Postman Collection とは？
知らない方のためにも一応解説しておきます。
Postman は Web API のテストや検証・開発をGUIベースで手軽に実施することができるアプリケーション です。
そのPostmanで管理しているリクエストをサービス単位等でまとめたものが、Postman Collectionです。
Postman Collection にまとめることで、認証方法やパラメータの定義を共通的に利用したり、API の自動テスト・開発チームでのリクエストのシェアを行うことができるようになっていて、とても便利にAPIの検証・開発を行うことができるようになっています。
また、海外を中心に各クラウドサービスベンダーがPostman Collectionを公開してDeveloper への利便性・APIの活用を促進する仕掛けも提供しています。
以下は、そんなPostman Collectionおよびそこから生成されるドキュメントをまとめて公開しているPostmanのサービス「API Network」です。
explore.postman.com
通常Postmanのリクエストは手動で一つ一つ「メソッドはなんだー」「URLはどうだー」「認証方法はこうかー」みたいな感じで設定して作り込んでいきます。ただ、そうなるとGUIとは言え、API仕様を紐解いていくのが大変だったり、今回のように機能が多い場合は網羅するのが億劫だったりします。
でも、上記のような形で PostmanCollection を公開してくれることで、一気にAPIを使うための敷居を下げてくれる役割も果たします。開発するためだけでなく、使う側にとっての仕組みでもあるわけですね。
そんな便利な Postman Collection ファイルを backlog 用にアンオフィシャルで作成して公開しました！ というのが、今回のお話です。
使い方
Collection ファイルのインポート
使い方は簡単です。ここ のGithub リポジトリからJSONファイルをダウンロードして、Postmanにインポートするだけです。
認証設定
Collection には予めAPI Keyを使った認証が実施できるようになっているので、backlog のユーザー設定画面から、API Keyを生成し、環境変数を書き換えてください。合わせて接続先のURLも調整してください。
データの取得
GET系のエンドポイントはデータを取得することができます。「プロジェクト一覧の取得」や「課題一覧の取得」はそのまま実行して試すことができます。
また、Paramsには backlog APIで利用できるすべてのクエリパラメータが登録されています。実行したいクエリを有効化して、任意のパラメータ値を設定すれば簡単にフィルターなどが実施できます。
DescriptionにはAPI Referenceから引用したパラメータの説明文も入っているので、どんな値を設定すればいいかもわかりやすいかなと思います。
データの追加・更新・削除
データの登録・更新・削除も実施できます。以下はプロジェクトの操作例です。
Bodyタブに予め登録できるパラメータの一覧が表示されているので、必要な値を入力もしくは入力しないパラメータを無効化してリクエストしてみてください。VALUE欄には予めその値の型も指定されていますし、Descriptionで必須項目かどうかも確認できます。
添付ファイルの送信
ほとんどの操作は上記手順で実施できますが、例外として「添付ファイルの送信」機能があります。
これはBodyのValue欄からファイルを選択して実行します。
コードから実行
また、プログラムから実行したい場合にもPostmanは便利です。Codeスニペットの機能を使って、各プログラミング言語での簡単な実行コードを入手できます。
以下はVisual Studio から C# で backlog の APIを実行してみたものです。
こんな感じでPostman Collectionがあるととても便利にAPIを試して、開発に活かすことができます！
作り方と補足とか
ちなみに今回のPostmanCollection の作り方ですが、一つ一つ地道にリクエスト・・・みたいなことはせず、以下の backlog API ReferenceからC#でかき集めました。
developer.nulab.com
そしてそれをPostmanCollection のJSON仕様にしたがって、組み上げて生成しています。要望があれば生成プログラムも公開したいと思いますが、基本的に一発フロー処理なので地道に取得して、地道にJSONを組み上げているだけです。
なお、Postman Collection は OpenAPI からも生成することができます。
kageura.hatenadiary.jp
なので OpenAPI Specを提供しているAPIならそれが楽なのですが、backlog サポートに問い合わせしてみたところ、現在そういったAPI Specは使われていないとのことだったので、今回はこのような手段を用いてみました。
API Maticというサービスを使えば、Postman CollectionからOpenAPI Specの下地を自動生成もいけるかな？ と思っていますが、今回はリクエストの中にレスポンスのサンプルを加えていないので、あまりいい生成はできないかなと思います。
kageura.hatenadiary.jp
おわりに
しっかりとしたPostmanCollection を作って公開するのは初めてなので、もし何か要望や足りないところがあれば、Github の Issue まで質問・要望ください。
ちなみに今回の検証で以下のようなAPI連携（PowerBI - backlog）ができました。是非みなさんも backlog と様々な連携を実現してみてください！
https://www.cdata.com/jp/blog/2019-12-24-113651
www.cdatablog.jp
関連コンテンツ
