🎴

Postman 入門

2023/08/23に公開

API

Web

Postman

tech

はじめに

今回の記事では、API設計・開発で重宝するサービス「Postman」の使い方を解説する。

対象者

これからPostmanを学ぶひと
実務でPostmanを触っているひと
Postmanに興味があるひと
タイトルでなんとなく気になったひと

Postmanとは

PostmanはWeb API(以下「API」)の設計・開発、テストをサポートするツールである。Postmanには以下のような機能と特徴がある。

APIのテスト：エンドポイントへのリクエストを送信して、レスポンスを確認できる
ドキュメンテーション：APIのエンドポイントに関する説明や詳細を簡単に作れる
モックサーバ：バックエンドがない場合でも、仮のレスポンスを返すAPIを模倣できる
テストの自動化：APIのエンドポイントを自動的にテストするスクリプトを作って実行できる
変数の管理：異なる環境や条件に応じて変数を設定し、APIリクエストのパラメータとして実行できる
コレクション：関連するAPIリクエストをグループ化して共有したり再利用したりできる

なぜPostmanがAPI設計・開発、テストで使われるのだろうか？

まず、APIのテストやドキュメンテーション作成、モックサーバの利用などを通じてAPIの開発を効率的に進められる。このツールを使うことで、エンドポイントの挙動をリアルタイムで確認しながら開発を行い、エラーや問題を早期に発見できる。さらに、Postmanのコレクションやドキュメンテーションの共有機能は、チーム内での情報共有や協力作業をスムーズに行える。また、Postmanを使用することで、API開発に関する知識やベストプラクティスを深め、自らのスキルセットを拡大できる。

多くの開発者や企業が既にPostmanを採用しているため、Postmanに精通していることは、多種多様なプロジェクトや環境で作業を行う際の大きなアドバンテージとなるだろう。

主な活用事例――Whatsapp

Postmanを導入している会社の代表例として、Whatsappが挙げられる。

Whatsappはメタ(旧Facebook)が運用している世界最大級のメッセージングサービスである。Whatsappの公式ブログの情報によると、2021年現在でWhatsappのユーザ数は20億以上である。

Whatsappは企業と顧客のコミュニケーションを強化するためのWhatsApp Business Platformを提供している。ところが、新しいAPIの迅速な統合のためのオンボーディングに課題があった。この課題を解決するため、WhatsAppはPostmanで自社のAPIとの連携を始めて、効率的なコミュニケーションを実現した。この連携により、開発者のオンボーディング時間が大幅に短縮され、APIとの連携がより直感的で効率的になった。

Postmanの画面

Postmanの画面は大きく分けてSidebar、Header、Workbench、FooterとRight sidebarの5つに分類される。

Header：ワークスペースへの作成、レポートへのアクセス、公開APIネットワークの探索などの機能がある。
Sidebar：Postmanの基本要素を担う。
Workbench：コレクションやAPIなどの要素と作業する場所。
Right sidebar：ドキュメント、コメント、リクエスト情報などのツールへのアクセスを提供する。
Footer：テキストの検索と置換、コンソール、リクエストやCookieのキャプチャなどを行う。

詳細

詳細に確認すると以下のようになる。

New - ここで新しいリクエスト、コレクション、または環境を作る。
Import - コレクションまたは環境をインポートする。ファイル、フォルダ、リンクからのインポート、テキストの貼り付けなどのオプションがある。
My Workspace - 個人またはチームで新しいワークスペースを作れる。
Invite - チームメンバーを招待することで、ワークスペース上で共同作業を行うことができる。
History - 過去に送信したリクエストが履歴に表示される。これにより、自分が行ったアクションを簡単に追跡できる。
Collections - コレクションを作成することで、テストスイートを整理できる。各コレクションには、サブフォルダや複数のリクエストを含めることができる。また、リクエストやフォルダを複製できる。
Request tab - 作業中のリクエストのタイトルが表示される。デフォルトでは、タイトルのないリクエストには「Untitled Request」が表示される。
HTTP Request - これをクリックすると、GET、POST、PUT、DELETEなど様々なリクエストのドロップダウンリストが表示される。Postman APIテストでは、GETとPOSTの２つが最もよく使われる。
Request URL - エンドポイントとも呼ばれ、APIが通信する先へのリンクを特定する。
Save - リクエストに変更がある場合、新しい変更が失われたり上書きされたりしないよう、Saveをクリックする必要がある。
Params - キー値など、リクエストに必要なパラメータを記述する。
Authorization - APIにアクセスするためには、適切な認可が必要だ。ユーザー名とパスワード、ベアラートークンなどの形式がある。
Header - コンテンツタイプJSONなど、組織のニーズに応じてヘッダーを設定できる。
Body - 一般的にPOSTリクエストで使用されるリクエストの詳細をカスタマイズできる。
Pre-request Script - リクエストの前に実行されるスクリプト。通常、設定環境用のプレリクエストスクリプトは、テストが正しい環境で実行されるようにするために使用される。
Test - リクエスト中に実行されるスクリプト。レスポンスのステータスが問題ないか、取得したデータが期待通りか、あるいはその他のテストが行われているかなどを検証するためのチェックポイントを設定するためにもテストを行うことは重要だ。

前提知識

今回の記事ではJSONPlaceholderとPostman Echoを使う。実際にPostmanの説明をする前に、これらのAPIの概要を説明する。

JSONPlaceholder

JSONPlaceholderは、フロントエンド開発者等がREST APIのモックとして使用できる無料のオンラインRESTサービスである。このサービスは、テスト、プロトタイピング、またはプレースホルダーとしてのデータの取得に利用される。JSONPlaceholderは、典型的なデータ構造（ユーザー、投稿、コメントなど）を模倣するための偽のデータを提供する。

APIのテストを実行する上で強力なサポートを提供してくれるのだ。

Postman Echo

Postman Echoは、Postman内でリクエストをテストするためのサービスだ。Echoサービスは、送信したリクエストのすべての詳細を含むJSONレスポンスを返す。Postmanの公式ドキュメント「Postman Learning Center」では、サービスの仕様の説明でこのAPIが使われている。これは、認証やリクエストの設定を気にせずにリクエストを送信する簡単な方法を提供するためである。

リクエスト

`GET`

GETリクエストは指定されたURLから情報を取得するために使われる。例えば、以下のURLでGETリクエストを実行することを想定する。

https://jsonplaceholder.typicode.com/todos/1

やり方は以下の通り。

HTTPリクエストをGETに設定する。
URLフィールドに該当するURLを入力
「Send」をクリックする
200 OKが出力される
テストが成功したら以下のようにJSONリクエストが出力される

`POST`

POSTリクエストはGETリクエストとは違い、ユーザがエンドポイントにデータを追加してデータを操作する。

まずは新規タブを追加する。

新規タブを追加した後は、以下の手順に従う。

HTTPリクエストをPOSTに設定
URLを入力
「Body」タブに切り替える

「raw」をクリックし、「JSON」を選択する。

以下のコードをコピペする。

{
      "userId": 1,
      "id": 100,
      "title": "hogehogehoge",
      "completed": false
}

成功すれば、以下のように表示される。

変数

変数の概念について、Postmanでは変数を使用することで値を保存し再利用できる。これを利用することで、コレクション、環境、リクエスト、テストスクリプト全体で変数を参照できる。

Postmanにおける変数の作り方は以下の通りである。

右上のアイコン(画像1参照)をクリック
Globalの「add」をクリック
画像2にて、「Variable」にmy_variable、「Initial value」にHelloを入力
「Save」を入力してタブを閉じる
https://postman-echo.com/get?var={{my_variable}}を指定のフォームに入力して「Send」をクリック。
JSONレスポンスが出力される

▼画像1

▼画像2

▼画像3(実行結果)

▼上述の手順で出力されるJSONレスポンス

{
    "args": {
        "var": "Hello"
    },
    "headers": {
        "x-forwarded-proto": "https",
        "x-forwarded-port": "443",
        "host": "postman-echo.com",
        "x-amzn-trace-id": "Root=1-64e5b130-6bf2d56e0c4386fc5f88fb1d",
        "content-length": "0",
        "user-agent": "PostmanRuntime/7.32.3",
        "accept": "*/*",
        "cache-control": "no-cache",
        "postman-token": "7385196d-21f8-485e-b71b-b37636f8bee3",
        "accept-encoding": "gzip, deflate, br",
        "cookie": "sails.sid=s%3AqyZ9L4jLtFZzvMmAPlonLjRCyD0qSxfb.3IKybcqhe7YDWtZMEPo6LQbwF2Sk0hPF0pQqrco47Ms"
    },
    "url": "https://postman-echo.com/get?var=Hello"
}

Postmanでは、開発、テスト、コラボレーションのさまざまなタスクに対応するための異なるスコープの変数をサポートしている。スコープは、global、collection、environment、data、localの順に広がっている。さらに、globalとenvironment変数はタイプによっても定義でき、利用可能なタイプにはDefaultとSecretの2つがある。変数はリクエストビルダー内の任意のスコープで定義することができ、スクリプト内で変数をプログラム的に設定できる。

Postman全体で変数を参照する際には、二重中括弧、例えば{{username}}のように使う。また、未解決の変数は、リクエストで使用される変数が利用可能なスコープ（環境、コレクション、またはグローバル）で定義されていない場合に発生することがある。

コレクション

Postmanのコレクションは、保存されたリクエストのグループを指す。Postmanで送信されたリクエストは、サイドバーのHistoryタブに表示されるので、小規模で使う際(例：個人開発)には、この履歴セクションを通じてリクエストを再利用することが便利だ。しかし、Postmanの使用頻度が増えると、履歴内で特定のリクエストを探すのは時間がかかることがあるため、履歴セクションをスクロールするよりも、リクエストをグループとして保存して簡単にアクセスする方が効率的である。

Postmanでコレクションを作るには、以下の手順を踏む。

「New」をクリックし、「HTTP」を選択する。

以下のURLを指定のフォームに入力し、「Save」をクリックして保存する。

https://jsonplaceholder.typicode.com/albums/3

テストスクリプト

テストの主な目的は、APIが期待通りに動作しているか、サービス間の統合が信頼性を持って機能しているか、そして変更が既存の機能を壊していないかを確認することにある。Postmanを使用すると、APIリクエストのテストスクリプトをJavaScriptで作れる。

テストは個別のリクエスト、コレクション、またはコレクション内のフォルダに追加できる。

最初に「+」ボタンをクリックして新しいタブを開く。その後、テストを行う手順は以下の通り。

「Test」をクリックする
リクエストの種類を選択する(GET、POST、PUT、DELETE)
リクエストを送信するURLを入力する
「Send」をクリック

画像にあるテストスクリプトは以下の通り。

pm.test("Status code is 200", function () {
    pm.response.to.have.status(200);
});

上述のコードは、ステータスコードが200番であることをテストすることを意味している。

他にも、Postmanでは以下のようなテストスクリプトを実行できる。(あくまで紹介のみ)

// レスポンス時間が500ms未満を検証
pm.test("Response time is less than 500ms", function () {
    pm.expect(pm.response.responseTime).to.be.below(500);
});

// レスポンスがJSONボディを持っていることを検証
pm.test("Response has JSON body", function () {
    pm.response.to.have.jsonBody();
});

// JSONボディに特定のキー(ここではkeyName)が含まれているかどうかを検証
pm.test("JSON body contains specific key", function () {
    var jsonData = pm.response.json();
    pm.expect(jsonData).to.have.property('keyName');
});

テストスクリプトを作るには、動的変数を使用したり、レスポンスデータに対するアサーションを実行したり、リクエスト間でデータを共有したりできる。リクエストのTestsタブでは、JavaScriptを手動で入力することも、コードエディタの隣にあるSnippetsを使うこともできる。(今回の記事では割愛する)

リクエストが返すデータの検証には、テスト内でpm.responseオブジェクトを使う。また、よく使用されるテストコードスニペットのキュレーションされたリストを利用して、テストコードを書くのをサポートする。コレクションやフォルダ、あるいはコレクション内の特定のリクエストにもテストスクリプトを追加できる。テストに何らかの問題が発生した場合、スクリプトにエラーがないかを確認することが重要だ。

参考記事

https://ja.wikipedia.org/wiki/WhatsApp

GitHubで編集を提案