New Year Calendar 4日目
New Year Calendarって何ぞという方はまずこちらをご覧ください。
つい最近プロジェクトでAPI仕様を管理する為にPostmanというREST APIクライアントツールを導入しました。
その時の経緯と調査内容、そして導入結果を共有します。
導入の経緯
それまでのAPIの管理
僕らのプロジェクトではドキュメンテーションツールとしてConfluenceを使用しています。
いくつかのAPI仕様はConfluenceに記述していましたが、全体のAPIの半分も満たしていませんでした。
その上、新しい機能で必要とされる新しいAPIは記述していなかったし、既に記述があるAPIで仕様の変更があっても更新がされていませんでした。
なので、開発者が自分が知らないAPIについて詳しく知りたいと思ったら
- 誰か知っているメンバーに教えてもらう
- 誰も知らなかったら自分でコードを見て調べる(「コードが正義だ」状態)
という、よくありがちな無駄作業が発生していたのです。
正直これやばいと思った
危機感を感じたのは、1ヶ月程前にフロントエンドリニューアルを行いサービス全体をSPA化することが決まった時でした。
今までサーバーサイドレンダリングをしていた箇所をAPIに置き換える作業が必要となり、また既存の古いAPIも規約に沿った形に修正する必要があると皆で話し合っていました。
その時僕らは気づいてしまったのです。
「そういえばAPIの規約はあるけど、各APIの仕様ってどこに載ってたっけ？」
「Confluenceに少しあったような・・」
「え？他のAPIは？」
「・・・
」
「全体でどれぐらいのAPIがあって、何のAPIを新しく作らなきゃいけないんだ・・？」
「・・・・・・」
「「「APIちゃんと管理しようぜ(汗)！！！」」」
そう、まるで出川状態に陥ったわけです。
出典元
APIを管理する上で必要な要件
まずどのようなツールがあるかを調べる前に、これからAPIを管理する上で必要な要件をまとめることから始めました。
最低限の要件としては以下の三つです。
- API仕様をチームで共有できる
- 記述されている仕様に基づいて簡単にAPIを実行できる(APIクライアント)
- 管理・運用が楽(更新がしやすい＆忘れない)
特にチームでAPIを管理する上で重要な点は運用が容易であることです。
以前僕は違う現場でSwaggerを使っていたことがありますが、Swagger-PHPでPHPメソッドにSwaggerのアノテーションを馬鹿みたいに長く書かなきゃいけないのが非常に苦痛でした。
API管理する為に実装で苦痛を伴うのは元も子もありません。
苦痛を伴う作業は開発者は都合良く忘れがちで運用を困難にします。
またAPI仕様とコードは分けるべきです。
例えばSwaggerのアノテーションが間違っていて、それを修正する為にアプリケーションコードに手を加えるのは適切ではありません。
(※これらは個人的な見解でありSwagger自体を批判しているわけではないので悪しからず)
管理・運用を楽にする意味の一つに、APIを実行する環境はなるべく自分達で用意せずクライアントに任せるというのも含まれています。
そんなわけで「チームでAPI仕様の共有ができる」REST APIクライアントツールの調査をすることにしました。
比較
調査にあたって、まず以下のようなツール比較の記載があるいくつかの記事を参考にしました.
チームでのAPI開発の強い味方!!REST APIクライアント「Paw」と「Insomnia」を比較してみた
ただ僕らのチームにはMacだけでなくWindowsを使用している開発メンバーもいたため、Macだけしか対応していないPawは速攻で候補から外れました。
最終的に候補に残ったのがPostmanとInsomniaの二つです。
まずそれぞれの見た目ですが、試しに楽天商品検索APIでGETした時を比較してみると、このような画面になります。
Postman
Insomnia
この二つのツールを詳細に比較したのが次の表です。
各項目の比較表
| 項目 | Postman | Insomnia |
|---|---|---|
| チームでAPI仕様の共有 | ◯ TeamでCollection(API設定のグループ)を共有 詳細 |
◯ TeamでWorkspace(PostmanのCollectionにあたる)を共有 詳細 |
| 料金(チームで使う場合の最低料金) | 1人8ドル/1ヶ月 詳細 |
1人8ドル/1ヶ月 詳細 |
| RequestHeaderの設定 | ◯ 詳細 |
◯ |
| パラメータの設定 | ◯ | ◯ |
| オープンソース | △ 本体ではなく関連ツールなら公開されている GitHub |
◯ GitHub |
| 環境ごとの変数の設定 | ◯ 詳細 |
◯ 詳細 |
| ドメインごとのCookieの設定 | ◯ 詳細 |
◯ 詳細 |
| 動的な値の埋め込み | ◯ | ◯ |
| 設定のimport/export | ◯ | ◯ |
| Chrome extension | ◯ extension |
◯ extension |
| テスト | ◯ | × |
| リクエストのタブ機能 | ◯ | × |
| チームメンバーの権限設定 | ◯ | × |
(※2017年12月時点)
Postmanしか出来ないこと
Insomniaで出来ることはほぼPostmanでも出来ます。
しかし表を見て分かるようにPostmanにしか出来ないことがいくつかあります。
テスト
InsomniaにはないPostmanの強力な機能がテスト機能です。
公式に記載されているようにJavaScriptで記述してAPIのテストをすることが出来ます。
// example using pm.response.to.have
pm.test("response is ok", function () {
pm.response.to.have.status(200);
});
実際の↑のテストケースを記述した後APIを実行してみます。
テストが実行され、正常に通っていることが分かりますね
さらにAPI単位ではなく、Collectionの下にある全てのAPIを一括でテストすることも可能です。
CollectionとはPostmanではAPIリクエスト設定をまとめた親グループを指します。
Collectionの下にフォルダを追加し、その下にAPIリクエスト設定をまとめることも出来ます。
下の例だとSample1というCollectionがあり、その下にIchibaとBooksというフォルダを置いています。
またIchibaとBooksのフォルダ内にそれぞれのAPIリクエスト設定を格納しています。
では先程言った「Collectionの下にある全てのAPIの一括テスト」を実行してみましょう。
Sample1のCollectionにマウスオーバーすると右に「>」アイコンが表示されますのでクリックします。
すると右側にウインドウが表示されるので青い「Run」ボタンをクリックしてCollection Runnerというテスト設定画面を表示します。
テスト設定画面では左側がテスト設定、右側がテストの実行履歴になります。
ひとまず設定は何も変更せず「Run Sample1」をクリックしてテストを実行します。
するとこのようにSample1のCollection下のテストを一括実行してくれてテスト毎の結果が表示されます。
この実行結果はJson形式でExportすることも可能です。
もちろん既にRSpec等でAPIテストしている方はこの機能は不要かもしれませんが、特にAPIテストを行っていない方はPostmanにAPI仕様とテストケースを集約出来るので便利だと思います。
リクエストのタブ機能
Insomniaはシンプルな作りとなっており、リクエストを実行できるウインドウが一つしかありません。
対してPostmanはタブ機能によって複数の異なるAPIリクエスト設定が出来るようになってます。
これは地味に嬉しい。
また以下の様にタブの複製も可能ですので、例えば一つのAPIでもパラメータが違う時のレスポンスを比較したい場合にもスムーズに設定出来ます。
チームメンバーの権限設定
プロジェクトによってはメンバー毎に参照はOKだけど編集権限は無しにしたい、参照・編集権限どちらもつけたいといった権限設定を行いたい場合もあります。
残念ながらInsomniaには現在メンバー毎の権限設定はありません。
PostmanならWebのダッシュボードのチーム設定で以下の様に権限をメンバー毎に付与することが出来ます。
結論
チームで使う場合の最低料金はどちらも1人につき8ドル/1ヶ月で同じ料金となります。(例.5人で使うとしたら1ヶ月40ドル)
Insomniaの方がシンプルで使いやすいですが、慣れてきたらPostmanの方が柔軟にカスタマイズ出来るのと、前述したPostmanの魅力に惹かれて、最終的にPosmanをプロジェクトに導入することに決定しました。
導入してまだ1ヶ月も経ってないですが、既に新しいAPI実装時にレスポンスを確認する時に役立てています。
またAPI実装後にGithubPull Requestを作る時も「PostmanのこのAPI仕様見てね」と説明欄に書いておくだけで共有が出来るので、開発効率が上がったのを実感。
なんでもっと早く導入しなかったんだろうと若干悔しい思いをしています(苦笑)
もし同じ様にチームでのAPI管理にお悩みの方はぜひPostmanを使ってみるのはいかがでしょう。