こんにちは。エクセルソフトの田淵です。
先日、API ManagementツールのKONGを触ってみた | エクセルソフト ブログというエントリーを書きましたが、curl や Httpie を使用することで API を叩いていました。
REST を叩くなら Postman がおすすめだよ。と教えてもらいましたので、触ってみました。
2019/11/04 に大幅に加筆修正しました。
Postman とは
The Collaboration Platform for API Development
とあるように、API 開発をする際にアクセス、モック作成、テストなどを個人やプロジェクトで使うことができる API クライアント／サーバーです。（全部入りと思って大丈夫w）
このエントリーでは Postman の API クライアントとしての様々な機能を紹介します。
インストール＆ユーザー登録
Postman のサイトにアクセスして、「Download the App」からインストーラーをダウンロードします。
インストールして起動すると、ユーザー登録が促されますので、そのまま登録します。（登録すると後述する Collection を Postman 側に保存して別マシンと同期することができるので登録することをお勧めします。）
最初の画面です。多機能だとは思うのですが、とりあえずは枠に URL を入力して「Send」ボタンをクリックすれば URL に対して HTTP リクエストを投げることができます。
GET／POST してみよう
例えば curl では以下のように書く POST リクエストを Postman でやってみましょう。
$ curl -i -X POST \ --url http://localhost:8001/apis/ \ --data 'name=test' \ --data 'uris=/test' \ --data 'upstream_url=http://httpbin.org'
送信方式を POST にし、右側の欄に URL を入力し、data として渡していた「name=test」などをそのまま body の key と value として入力していきます。
ステータスコードも右側に出て、リターンの Body が表示されています。Header もチェックできますね。ちなみに、上記のスクリーンショットは Ubuntu でのものです。
次は curl では次のように書く GET リクエストを Postman で送ってみましょう。
$ curl -i -X GET \ --url http://httpbin.org/anything?data=value
送信方式を GET にして、Param の欄に Key と Value を入力すると、自動的にパラメーターを追加してくれます。
戻り値の JSON の Body は Pretty で見やすく表示されていますが、以下のように生データとしてコピーすることもできます。
POST で form data や application/json を送信してみよう
POST で form-data を送る場合は、POST を選択し、Body で form-data を選んで key と value を入力して Send します。
JSON データを送る場合は、Body で raw を選択し、右側のドロップダウンから JSON (application/json) を選択して、JSON を直接入力します。（自動で Header に Content-type: application/json が指定されます。）結果は以下のようになります。
なかなか使いやすいですね！以下に、より便利に使うための TIPS を記載します。
Collection を使ってみよう
Collection は API へのアクセスをまとめておくためのフォルダと考えて良いでしょう。API へのアクセスを設定したタブで、「Ctrl+S」または「⌘+S」すると保存画面が出てくるので、任意の名前をつけて、「+ Create Collection」からコレクションを作成／指定して保存できます。
保存すると、以下のように左のペインにコレクション名と名前をつけたタブが保存されます。
変数を使ってみよう
Postman は変数を使うことができます。変数には Global／Collection／Environment 変数があり、Global は Postman 全体で利用できる変数。Collection は Collection レベルで参照できる変数。Environment は各 Environment（タブ）で利用できる変数です。
変数についての詳細は Variables | Postman Learning Center をご覧ください。
Global 変数
Global 変数は Postman 自体に格納する変数で、タブを超えて読み書きできるため、例えば「ログインした際の SessionID や UserID を格納して、その後のタブで {{PRJ-A_SESSION_ID}} や {{PRJ-A_USER_ID}} として参照する。」などの用途で使うと良いでしょう。（格納するには、後述する Script を使用します。）
右上の歯車アイコン⚙で Management Environment ウィンドウを開き、「Global」ボタンをクリックすると確認ができます。
Collection 変数
Collection 変数は、Collection 内で使い回す変数を格納すると良いでしょう。
Collection の右側にある「… ＞ Edit ＞ Variables」で作成／利用できます。
例えば、TEST_USER と TEST_PASSWORD を Collection に設定すると、それぞれ {{TEST_USER}}、{{TEST_PASSWORD}} として参照ができます。
以下のように値がちゃんと渡されているのがわかります。
Environment 変数
Environment 変数は、例えば開発環境と実行環境で参照する IP Address を変えたい場合などに利用します。
右上の歯車アイコン⚙で任意の名前をつけて保存します。例えば「PrjA-Development」環境では、Hostname をローカルホストに指定し、「PrjA-Production」環境では、実際の IP Address に指定するなどです。
右上の Environment 欄で Environment を指定できます。「PrjA-Development」を選択すると、{{Hostname}} が「PrjA-Development」で設定した IP Address になります。
Script を使ってみよう
送信前、送信後に値を設定、取得したい場合もあると思います。送信前に値をセットする場合は Pre-request Script、送信後に取得した値から任意の値を選んで変数に格納する場合は Tests を使います。
Pre-request Script では、例えば送信時の現在時刻を Reqest Body に追加したい場合などに便利です。
function changeFormat(date, format) {
format = format.replace(/yyyy/, date.getUTCFullYear());
format = format.replace(/MM/, ("0"+(date.getUTCMonth() + 1)).slice(-2));
format = format.replace(/dd/, ("0"+(date.getUTCDate() + 1)).slice(-2));
format = format.replace(/hh/, ("0" + date.getUTCHours()).slice(-2));
format = format.replace(/mm/, ("0" + date.getUTCMinutes()).slice(-2));
format = format.replace(/ss/, ("0" + date.getUTCSeconds()).slice(-2));
format = format.replace(/fff/, ("00" + date.getUTCMilliseconds()).slice(-3));
return format;
}
//"2019-08-27 00:48:24.766"
let nowDatetime = changeFormat(new Date(), "yyyy-MM-dd hh:mm:ss.fff");
pm.environment.set("NOW_DATETIME", nowDatetime);
Pre-request Script タブにこのスクリプトを記載すると、現在時刻をグローバル変数 NOW_DATETIME に yyyy-MM-dd hh:mm:ss.fff のフォーマットで格納してくれます。
後はリクエストの Body や JSON で {{NOW_DATETIME}} で参照できます。むっちゃ便利ですね。
Tests 機能は公式ドキュメント Test scripts | Postman Learning Center にあるように、本来は戻り値をテストする。などのためにあるのだと思います。
// example using pm.response.to.have
pm.test("response is ok", function () {
pm.response.to.have.status(200);
});
上記のように記載すると、レスポンスコードが 200 の場合にテストが通ります。以下のように Test Results のタブで結果を確認できます。
が、例えば「Response の Body に含まれる Token を Global 変数に格納して、それ以降のアクセスで使用する。」などの用途にも使用できます。こちらもむちゃくちゃ便利です。
JSON.parse(responseBody) で Response Body の JSON をパースして、pm.globals.set でグローバル変数 “PRJ-A_TOKEN” に json.token を格納しています。
pm.test("Set Variables", function(){
let json = JSON.parse(responseBody);
pm.globals.set("PRJ-A_TOKEN", json.token);
});
後はこれ以降のアクセスで Bearer {{PRJ-A_TOKEN}} のように書けば Bearer XXXX のように Token でのアクセスができます。
Environment の操作方法は公式ドキュメントの Postman Sandbox | Postman Learning Center もご参照ください。
まとめ
単純にアクセスするだけでなく、変数やスクリプトを使うことでめちゃめちゃ便利に使える Postman をぜひ活用していきましょう！
宣伝
著者の @ytabuchi が所属する エクセルソフト は、開発者向けのツール、ライブラリ、クラウドサービスなどを多く提供しています。是非弊社サイトも覗いていってください。
API あるけど認証やロギングなどの機能を追加するの大変そう。という方は、OSS 版も用意されている API Management ツールの Kong を試してみてください。
Kong については簡単なハンズオンも ytabuchi の GitHub に用意しました。
API のテストがしたいなって方は SmartBear SoapUI Pro : Web API 機能テスト ツール :エクセルソフト をお試しください。
API のコントラクト テストに興味がある方は、Postman と Pact の違いに関する記事もご覧ください。
API まだないからなーという方は MS SQL、MySQL、PostgreSQL などから簡単に API を作成することができる CData API Server を試してみてください。
以上です。
