2019/12/09

Postmanを活用したバックエンド開発事例の紹介

WRITER: k.haga

こんにちは。開発G所属のサーバサイドエンジニアです。

10ANTZのコンテンツでは、キックオフしてからわずか3ヵ月でリリースしたコンテンツがあります。

とても厳しいスケジュールでしたので、サーバ・クライアントの認識齟齬が発生しないように工夫して開発する必要がありました。

そんな時に大活躍したソフトウェアのPostmanを今回紹介したいと思います。

 


Postmanとは


API開発用のプラットフォームです。

  • ドキュメント生成
  • モックサーバ
  • APIクライアント
  • 自動テスト
  • モニタリング

といった、API開発に欲しい機能が兼ね備えられています。

「so you can create better APIs—faster.」らしいです。

 


ドキュメント生成


実際にpostmanを使ってAPI仕様書を作成してみます。

Collectionsを使う方法はいろんな人が記事を書いていると思いますので、今回はAPIs(BETA)を利用してみます。

API名、バージョンを定義した後のスクリーンショット

APIスキーマを設計する


「Define」タブでは、APIスキーマを設計したり、ファイルからAPIスキーマをインポートすることができます。

今回はOpenAPI3.0のyaml記法でAPIスキーマを定義してみました。

APIスキーマ定義

 

CollectionsにAPIを追加し、ドキュメントを生成する


「Save」> 「Generate Collection」の順に進んで、CollectoinsにAPIを追加していきます。その時に一緒にDocumentも生成されます。

「Save」> 「Generate Collection」

 

Collectionsに追加されたAPI

 

Documentが生成されていることの確認
生成されたドキュメント

 

OpenAPI3.0でスキーマ定義をする利点


今まではCollectionsでAPIを作成していたため、例えば User という構造体に変更が入った場合、 User を返却するAPI全てのレスポンスを手動で直していました。Collectionsしか使っていない方は同じような経験があるのではないでしょうか。

OpenAPIを利用すると、各APIのレスポンスは components を参照できるため、 User を components に定義しておけば勝手に各APIのレスポンスに適用されます。

 


モックサーバ


postmanのモックサーバにはpublic/privateの2種類があり、privateの場合は api-key を HTTP リクエストヘッダに入れてリクエストします。

モックサーバがあれば、バックエンド側のAPI開発が終わるまでフロントエンド側がAPI繋ぎこみができない。というようなことを避けることができます。

また、自前でモックサーバを構築している方もいらっしゃるかと思いますが、postmanに任せてしまえばそれらの作業も必要なくなります。

 

モックサーバの構築


「Develop」タブから 「Add Mock Server」 でモックサーバを作成していきます。

「Select a collection in this workspace」で先ほど作成した「ユーザ」Collectionsを選択してモックサーバを作成します。

モックサーバはデフォルトでpublic設定になってしまうので、必要な人は忘れずに「Make this mock server private」にチェックを入れましょう。

先ほど作った「ユーザ」というAPIスキーマからモックサーバを作る
モックサーバをprivateにして作成する
モックサーバが作成されたことの確認

APIキーの生成


先ほどモックサーバはprivateで作成したので、モックサーバへリクエストを送る際に X-API-KEY をHTTPのリクエストヘッダで送る必要があります。

APIキーは「Account Settings」>「Postman API keys」から生成することができます。

Account Settings

environmentファイルの作成


PostmanからAPIリクエストを送る準備として、モックサーバのURLとAPIキーを定義しておきます。

APIキー、URLの定義はenvironmentで定義しておきます。

environmentの新規追加
baseUrlとpostmanApiKeyの追加

 

envrionmentを追加したら、右上の「No Environment」プルダウンから今回追加した「demo」を選びましょう。

 


APIクライアント


先ほど作成したモックサーバに対してHTTPリクエストを投げてみたいと思います。

その時使用するのがAPIクライアントです。

APIクライアントからリクエストを送った例

 

上記スクショは青色の「Send」ボタンを押下した後のスクリーンショットです。

mockNotFoundError になっていますね。

エラーが不親切なのですが、これはHTTPのリクエストヘッダで X-API-KEY を送ってないからです。

X-API-KEY をセットしてリクエストを投げてみます。

AuthorizationにAPI keyを設定

 

モックサーバからのレスポンス

 

「Heads up! These parameters hold sensitive data. To keep this data secure while working in a collaborative environment, we recommend using variables.」

ということなので、先ほどenvironmentに postmanApiKey を設定しました。

今回はその変数を利用して {{postmanApiKey}} を設定しました。

「Send」ボタンを押すと、正しくAPIスキーマで定義したレスポンスが返ってきました。

 

 


自動テスト


PostmanはテストケースをAPI毎に作成することができます。

テストケースの例

 

テストケースを実行してみたいと思います。実行するには「Collection Runner」を立ち上げ、実行します。

Collection Runnerを起動

 

テスト実行例

「ユーザ情報を作成する」APIのテストケースに、わざとテスト失敗になるケースを書いておきました。

このスクショのように、テスト結果はGreen/Redで表示されます。

CommandLineToolも提供しているみたいなので、CI/CDと組み合わせればテストの自動化も行うことができそうです。

(今回の記事では自動化には触れません)

 

 


モニタリング


APIのレスポンスタイムやテスト結果をvisualizeすることができるツールです。

個人的にはレスポンスタイムがvisualizeされるのがとても嬉しいです。

 

モニター作成


「Observe」タブから 「Add Monitor」 でモニターを作成していきます。

「Select a collection in this workspace」で先ほど作成した「ユーザ」Collectionsを選択してモニターを作成していきます。

モニターの新規作成1

 

モニターの新規作成2
モニターの作成画面

 

グラフの確認


スクショの赤枠のところをクリックして、webページに飛びます。

モニタリングツールの起動

 

実際に何度かAPIを叩いてみた後のグラフです。

API実行結果

 

このように、テストの実行結果やレスポンスタイムがvisualizeされて表示されます。

機能が追加されたりすると途端にレスポンスタイムが悪化することがありますが、モニタリングを活用することによって事前にレスポンスタイムの悪化を確認できるのは嬉しいですね。

 


まとめ


今回はPostmanの機能紹介をメインに書いてみました。スクリーンショットばっかりですね。。

PostmanはAPI開発において、開発者のことを考えた機能がたくさんあることがわかったと思います。

10ANTZの短い開発期間でのコンテンツ制作を支える大事なアプリケーションとして、社内でとても重宝しています。

APIの自動テスト、APIクライアント等の機能で良し悪しを決めてしまいがちですが、何よりもフロントエンド・バックエンドの共通認識を保つためのドキュメント、モックサーバは大変便利でした。

お互いの作業待ちを減らし、その分コミュニケーションが増えるので、チームとしての生産性もあがったと実感しています。

 

最後に、10ANTZではコンテンツの中身を大事にしています。

お客様が実際に目にするところだけでなく、中身のソースコードにも拘りを持って制作をしています。

今後もこういったブログという形で、10ANTZの開発事情なんかも発信できたら良いなと思っていますので、ちょくちょくブログを覗いていただけると嬉しいです。

 

k.haga

k.haga

開発Gサーバサイドエンジニア
自称アーティスト: 「プログラムは芸術」