Postmanを使ったAPI設計

バックエンドAPIの開発においては、実装前にAPIの設計・仕様を決めます。Postmanは、バックエンドAPIに対するAPIクライアントとしての機能が大変優れているのみならず、APIの設計・仕様を決める工程においても威力を発揮します。具体的には、下記のPostmanの機能がAPIの設計で有用です。

• ワークスペースを頂点としたフォルダの階層構造
• 左側に階層構造、右側に各リクエストが表示される開発環境同様のUI
• リクエスト毎にドキュメントを記述可能
• API全体のドキュメントが一覧で見れる
• Inviteを使うとチーム内で共有が可能（ワークスペース単位）

Postmanのダウンロードと設定

postman.com/downloadsにアクセスしてデスクトップアプリをダウンロード、Postmanを起動したらWorkspace（ワークスペース）を開きます。始めはMy Workspaceになっていると思います。ワークスペースは原則チーム内で共有する場合の範囲（単位）になりますので、自分の所属するチーム毎にワークスペースを分けるということだと思います。画面の左側にワークスペース内のフォルダ構成が表示され、右側に左側で選択した各リクエストが表示されます。Postmanでは最上位のワークスペースに続いてコレクション、フォルダ、リクエストという4層の構造をしています。

上記画面の左側上部にのNewという部分をクリックすると下記のようなポップアップが開くので、Collectionを選択・新規作成します。

すぐにNew Collectionという名称のコレクションが作成されますので、New Collectionの文字の部分を右クリックしrenameを選択（又はCtrl + E）、新たな名称を付します。コレクションの名称は一つのプロジェクトに対応した名称とするといいと思います。

続いてコレクションの右側にある○○〇の部分をクリックし、Add folderをクリックし、コレクション内フォルダを作成します。フォルダはなくても構いませんが、始めに作成したAPI設計から派生して、別のAPIの設計を試す場合などの場合には、フォルダそのものの複製が可能なことから、フォルダを作っておいた方が便利だと思います。また、ドキュメントがコレクション単位ではなく、フォルダ単位になりますので、API設計としてPostmanを使用する場合はフォルダはあった方がよいです。

フォルダの新規作成時はNew Folderという名称なので、コレクションの名称変更時と同様に文字の部分を右クリックしてrenameを選択、フォルダの名称を変更します。ここではコレクション名をMyRESTAPI、フォルダ名をMyRESTAPI_mainとしました。

APIエンドポイントの設計

今回は店に商品を登録する CRUD APIを設計するとします。エンドポイントは3つです。

1. 商品一覧を取得する/products
2. 各商品を登録する/product/<name>
3. ログイン認証のための/auth

①はGETのみ、②は登録POST、照会GET、変更PUT、削除DELETEを可能とする4つのVerb（メソッド又はプロトコルとも呼ぶ、以下メソッド）、③はPOSTのみとします。②の<name>の部分ではパスを商品名の変数としています。

続いてMyRESTAPI_mainフォルダ作成時のAdd a requestの部分をクリックするか、先ほど作成したフォルダ内の右側をクリックしてAdd requestを選択、新しいリクエストを作成し、①を設計します。①のHTTPVerbはデフォルトのGETままに、urlの部分にエンドポイントを記述します。BASE URL（ホスト名）をローカルホスト5000とすると、urlはhttp://localhost:5000/productsとなります。①にはHeaderもBodyもないので、そのまま右上のSaveを押します。

フォルダ名を変更したのと同様の方法で、ファイル名を変更します。ファイル名の先頭にはHTTPメソッドが付されているので、ファイル名をパス名とすれば、わかりやすいと思います。

APIエンドポイントのドキュメント

次のエンドポイントを設計する前に、今作ったGET /productsファイルのドキュメントを記述します。リクエストの内容はファイルを見れば自明ですので、ドキュメントには主にこのリクエストの目的とレスポンスを記述します。ファイル名の右にある○○〇をクリックし、View Documentaionをクリックするとドキュメントファイルが開きます。

ドキュメントファイルを開くと、コレクション及びフォルダにもドキュメントを記述できると思いますので、右側にあるペンのアイコンをクリックして、それぞれに記載します。

APIエンドポイントの設計（POST他）

続いて、/productsファイルを作成したのと同じ方法で各商品を登録するための/product/<name>エンドポイントを作ります。/product/<name>エンドポイントは4つのHTTPメソッドに対応するのでファイルも4枚作ります。一つのリクエストファイル内で、HTTPメソッドは変更可能ですが、同一のAPIエンドポイントでもメソッドによって、ヘッダーやボディ（ペイロード）が異なることも多いので、1枚のファイルで済ますのではなく、メソッド毎に別のリクエストファイルを置いた方が設計も後の開発・テストもずっと容易です。

/product/<name>はPOSTからファイルを作り、urlとファイル名を入力しsaveます。続いて、POSTのファイルの内容（HeadersやBody）やドキュメントを記述する前に同じファイルをメソッドの数（本事例では4枚）だけ複製（Duplicate）します。こうするこで、4枚のファイルに共通なurlの部分をいちいち書かずに済みます。なお、本件の場合はurlに<name>という変数のパスが入っていますが本事例ではこの段階でulrに具体的な商品名<name>を入れておりません（ドキュメントにその旨を要記述）。開発・テスト時は、ここに/products/noteなどの具体的な商品名を入れてリクエストします。

HTTPメソッドの数だけファイルを複製をしたら、urlは同じですので、それぞれのHTTPメソッドを変更してSave、ファイル名は全て同じpathにします。下記の図で左側が複製直後、右側がメソッドとファイル名変更後になります。

Postmanでのヘッダーとボディの書き方

次に作った4枚のリクエストファイルの内容を設計します。ここではPostmanの使い方を網羅できないので、簡単なヘッダーとボディを含むPOSTの事例で紹介します。さてPOSTでは（１）商品名をパスの変数とする、（２）商品の情報（本件では価格のみ）をボディーにJSONで記載するよう設計してみます。また、（３）ヘッダーには認証（JWTのAuthorizaion）を要するとします。

ファイルを開き、まずはヘッダー（Headers）を記述します。今回は（２）でボディをJSONとし、（３）の認証を付けたいので（そのように設計したいので）、下記の内容をPostmanのリクエストファイル内のHeadersに記述します。なお、JWT認証ではJWTとトークンの間に半角スペースが必要です。

次にボディに、価格の情報をオブジェクトで記載します。ここでは設計上もボディの具体例があった方がいいので、仮の価格で記入します。JSONをそのまま書くので、Ｂody内のrawを選択します（Saveも忘れずに）。

/productsファイルと同様にドキュメントを書いたら、残り4枚のファイル（/product/<name>のPUT、DELETE、GET及び認証の/authのPOST）についてもそのリクエストの内容とドキュメンテーションを整えます。それぞれPOSTと同様の手順で設計が可能ですのでここでは詳細割愛します。下記が今回の事例での完成されたドキュメントの一部です。

Postmanに記述されたAPI設計をもとにすれば、バックエンドの開発はスムーズになります。フロントエンドもバックエンドの開発を待つことなく、APIの実装が可能です。

応用編 – 環境変数の設定

上の例では、URLを直接各エンドポイントに記述していましたが、PostmanではURL（ホスト名）を環境変数として設定した上で、環境を切り替えて使用することが可能です。例えば開発環境と本番環境を行き来しながらPostmanをテストする場合、環境変数がなければ毎回全て（本件の場合5件）のエンドポイントのホスト部分の変更を要しますが、変数としてurlを設定しておけば、環境全体を切り替えるだけです。環境変数を設定するには、Postmanの右上の目のマークをクリックします。

右上の目のマークをクリックしたら、Environment（環境）ボックス内にあるAddをクリックします。

Addをクリックしたら、VARIABLEに変数名（ここではurl）、TYPEはdefaultのままとし、INITIAL VALUEにホスト名（ここではhttp://127.0.0.1:5000）を入力してSaveします。また、New Environmentとなっている環境名を変更します。ここではLocal Environment:5000としました。

環境変数の設定を終えたら、右上の環境部分で今設定した環境（Local Environment：5000）を選びます。複数の環境を設定したら、ここで切り替えることが可能です（開発環境 ⇔ 本番環境）。

設定した変数は、二重の波括弧の内側で使用できます。下記はGETリクエストのurl部分で設定したurlを使用している例です。全てのリクエストファイルで同様にurl変数を記述すれば完成です。

今日も最後まで読んで頂いてありがとうございました。