API実装でPostmanが便利
はじめに
こんにちは！G2 Studios サーバーエンジニアのL.Yです。
今回は、ゲームのAPI開発に欠かせないテストツールを紹介します。
皆さんはRESTful APIを開発する際、疎通確認やレスポンス形式の確認をするために、どんなツールを使っているでしょうか？
今回は弊社サーバーチームでよく使用されるPostmanの導入経緯を含めて紹介させていただきます。
※今回の記事ではPostmanのインストールと細かい操作関連は割愛させていただきます。
公式サイトからダウンロードへ： https://www.postman.com/downloads/
導入経緯
プロジェクトの初期段階でサーバー側が技術選定する際に、APIのテストツールについて議論しました。
▼チームメンバーとの話し合い（一部）
Aさん：動作確認が完了したAPIシナリオをメンバーに共有したい。
Bさん：確かに、機能毎に担当が違うので、既に確認済みのシナリオを簡単に取り込めれば、最初からシナリオ作成をする手間が省けますね。
Cさん：複数の開発環境が立っている場合、環境毎にシナリオ管理をするのは大変です。
Bさん：そうそう。環境毎にパラメータ違いは限られているので、APIサーバー実装と同じく、.envファイルを用意するだけで、簡単に切り替えられたら助かる！！
Aさん：環境毎のパラメータ設定と似たようなニーズですが、認証の都度、APIシナリオの認可用トークンを修正する手間がかかり、動的にAPIシナリオに設定して欲しいですね。
Cさん：そうですね。特に結合テストをする際、APIシナリオの前後関係を持っている場合、前者のレスポンスを後者のパラメータとして引き渡せば一連の動作を確認できるのが理想ですね。
Dさん：クライアント側と繋ぎ込みを行う際、レスポンスの構造が想定と違ったり、値の型が間違ったりするケースがたまに発生します。意図せず変更されたら、ゲーム進行不能になり、大きな事故に繋がります。開発段階で既に決めているレスポンスを常にチェックするようにできたら助かります。
チーム内の意見を纏めると、以下の要件を満たせば、ぜひ導入していきたいと考えました。
チーム内でAPIシナリオを共有したい
環境跨ぎの確認をする際、環境依存の設定を都度変更せずに切り替えたい
結合テスト／前後APIのパラメータを受け渡しの際、自動的に設定できるようにしたい
APIシナリオ実行するたびにレスポンスをチェックしたい
いくつか課題を持ちながら調べていたところ、Postmanが全部解決してくれました。
これからPostman公式用例を用いて、説明していきたいと思います。
メイン機能説明
APIシナリオファイルを共有
Postmanのアカウントは、無料プラン(Personal)と有料プラン(Team、Business、Enterprise)があります。チーム機能を利用したい時、３名以内ならTeamの一部機能を無料で使えますが、それ以上メンバーが増える場合は有料プランに切り替える必要があります。
Postman上で作成されたAPIシナリオファイルは、簡単にインポートとエクスポートが行えます。他のメンバーにAPIシナリオファイルを共有したい場合、ファイルを直接受け渡すこともできますが、Github等のソースコード管理SaaSを経由して共有するほうがお勧めです。
チーム人数が多い場合、有料プランの導入も検討してみると良いでしょう。チームアカウントを使用することで、チームに入っているメンバーはAPIシナリオファイルが変更されるたびにインポートとエクスポートをせずとも、変更が自動反映されます。そのため、共有の漏れがなくなり作業効率がアップします。
環境切り替え
ゲーム開発が進行していく中、用途によって開発環境／プランナー環境／QA環境／審査環境等が出来上がります。確認用APIシナリオは各環境に依存されている設定以外、基本は同じになります。Postmanに環境管理機能があり、環境依存の変数(ドメイン名／認証キー／ユーザーID等)を環境毎に設定し、環境を切り替える際に対象環境を選択すれば、APIリクエストの向き先が変わってくれます。
実際の操作イメージは下記の図の通りになります。
③ 環境設定 に $baseUrlは ① 環境切り替え によって、② 環境一覧 で設定している値に置換されます。
レスポンス受渡し
API単体テストする場合、特に前後関係がないので、決めたパラメータでAPIテストするのが一般的だと思いますが、ゲームアプリの動作を想定した結合テストする場合、前後関係のパラメータを受け渡す必要があります。Postman上のAPIレスポンスを変数に設定することにより、次のAPIシナリオのパラメータに使い回して、結合テストが可能になります。
下記のユースケースを想定して、変数の使い方について説明していきます。
商品アイテムリストを取得 GET /item?list=10
アイテムリストレスポンスからアイテムIDを設定
アイテムIDをパラメータとして該当商品詳細を取得 GET items/:itemId
アイテムIDを設定する
パラメータ設定(Params)の横のTestsタブに、APIレスポンスから特定の値を変数に設定することが出来ます。
今回の例でいうと、商品リスト配列から1個目のアイテムIDを itemId 変数に設定しておきます。次に実行するアイテム詳細APIのリクエストパラメータとして使われます。
実際の操作イメージは下記の図の通りになります。
① アイテム一覧API を実行し、 ② レスポンス を取得し、③ レスポンスのアイテム一覧から アイテムIDを設定しておく
対象アイテムIDの詳細を取得
アイテム詳細取得APIに対象アイテムIDを渡す必要あるので、先程に用意した itemId 変数 を {{itemId}} の形でパラメータ設定することで、パラメータの受渡しができます。
実際の操作イメージは下記の図の通りになります。
レスポンステスト
ゲームアプリが動作するには、クライアント側とAPI通信した結果をうまく噛み合わせる必要があります。サーバー側の疎通テストだけで、クライアント側が想定しているレスポンスが返されているかは不安になります。Testsタブでレスポンスに対して、想定通りに返されるかのテストコードを追加できます。
公式サイトにレスポンス結果を確認する方法が詳しく記載されているので、必要あればご参照ください。
実際の操作イメージは、下記の図の通りになります。
アイテム詳細のAPIレスポンスは description1 と想定してましたが、現行の実装は description が返ってきているので、エラーとなっています。
レスポンスの結果
レスポンスチェック
終わりに
Postmanでよく使われる機能を紹介させていただきました。
APIテストツールを用いる事で、より効率的に開発をする事ができます。紹介した機能以外にもRunner(自動化テスト)を使用してバグの早期発見に役立てたり、newman(サーバー版)を使用する事で負荷試験のシナリオとして使用する事もできますので、APIテストツール導入の参考になれば幸いです。
最後までお読みいただきありがとうございました。
▼G2 StudiosのCREATIVE記事をまとめたマガジンはこちら
▼G2 Studiosでは一緒に働く仲間を募集しています