Postmanの使い方

https://youtu.be/VywxIQ2ZXw4

Youtube動画の学習用メモです、APIの説明書はこちらです

Requestを送信

サンプルのAPIを使ってRequestを送信してみます

API URL：https://simple-books-api.glitch.me
Endpoint：GET /status
Description：APIの状況を返します

Postmanのホームページに行き、左上の「Workspace」をクリック、「My Workspace」をクリックします

タブの「+」アイコンをクリックします

URL欄に https://simple-books-api.glitch.me/status を記入します

「Send」をクリックします

下のパネルに返り値が見れました

Postman Collection and Variables

Collectionは複数のRequestのリストです、Collectionの中のRequestは全部同じAPIに繋がっています

先ほど作成したRequestを保存、そしてCollectionもついでに作成しましょう

「Save」をクリックします

Request nameを「API Status」に変更します
画面中央の「Create a collection」をクリックします

Collectionの名前に「Simple Book API」を記入します
「Create」をクリックします

作成後、Simple Book APIにクリックします

「Save」をクリックします

これでRequestの保存が完了しました
左パネルからアクセスできるようになりました

次は、APIアドレスを変数化にしてみます

「https://simple-books-api.glitch.me」をセレクト、「Set as variable」をクリックします

「Set as a new variable」をクリックします

Nameに「baseUrl」を記入します
Scopeに先ほど作成したCollectionを選択します
そして、「Set variable」をクリックします

URLの部分が変数化にしました
「Save」をもい一度クリック、保存します

もし、baseUrlを変えたい場合なら

左パネルのSimple Book APIの右のアイコンをクリックします

「Edit」をクリックします

「Variables」タブをクリックします

この画面でVariableを変えることができます
Initial valueは、他人と共有できるvalueです
Current valueは、自分だけ見れるvalueです

Query parameters

次はGET /booksを使ってみます

タブの右の「+」アイコンをクリックします

URL欄に「{{baseUrl}}/books」を記入します
しかし、{{baseUrl}}が無効だったようです
（まだCollection指定してないので）

Collection指定のために、「Save」をクリックします
Save toに「Simple Book API」をクリックします
（ついでにRequest nameもList of booksに変更します）
そして、「Save」をクリックします

GET /booksは二つのOptional query parametersがあります

• type: fiction or non-fiction
• limit: a number between 1 and 20.

Query parametersは、Request送信とともに一緒に指定できる引数です
必須記入の場合もあるし、非必須記入の場合もあります
（GET /booksは非必須記入です）

Query parameterを記入する場合は
まずはタブが「Params」にフォーカスしていることを確認します

KEYに「type」を記入し、VALUEに「crime」を記入します

そして、「Send」をクリックして送信してみます
しかし、失敗でした
以下のエラーが出ました

{
	"error": "Invalid value for query parameter 'type'. Must be one of: fiction, non-fiction."
}

typeは「fiction」と「non-fiction」しか記入できません
crimeを「fiction」に変更して、もう一度「Send」をクリックします
今回は成功でした

Query parameterは二つの特徴があります

• case sensitive：limitとLimitは違っている二つのparameterとして見れています
• 指定したparameter以外のやつを送信しても、無視されます

つまり、
{{baseUrl}}/books?limit=2を送信したら二つの結果が返します
{{baseUrl}}/books?Limit=2を送信したら全ての結果が返します（無効のparameterなので）

Path variables

次はGET /books/:bookIdを使います

タブの右の「+」をクリックして、新しいタブを開けます
URL欄に「{{baseUrl}}/books/:bookId」を記入します

「Save」をクリックして、モーダル画面を開けます
Request nameに「Get a single book」を記入して、画面の右下の「Save」をクリックします

これでOKです

今回のURLの{{baseUrl}}/books/:bookIdの「bookId」はPath parameter（あるいはPath variable）と言います

Path variableのKEYに「1」を記入します

送信してみると、該当IDのデータが出ました

POST Request

次はPOST /ordersをやっていきたいと思います

既存のAPIをDuplicateします

鉛筆のアイコンをクリック、名前を「Submit an order」に変更します

Request Typeを「POST」に変更します
URL欄に「{{baseUrl}}/orders」を記入します

POST RequestにはBodyが必須なので、Bodyのタブをクリックします

一旦ここで「Send」を押してみます、401のResponseが出ました

{
    "error": "Missing Authorization header."
}

オープンなPOST APIは、Authせずに利用することができますが
今回使ったAPIはプライベートなので、Authが必要です

今回のAPIはAuthの流れは、ユーザー登録POST /api-clients/です
なので、一旦POST /ordersを止めて、POST /api-clients/を先にやりましょう

API Requesetのタブを一つ作成して、
Request nameを「Register API Client」に変更し、
Request typeを「POST」に変更し、
URL欄に「{{baseUrl}}/api-clients」に変更します
（{{baseUrl}}/api-clients/もOKです）

Bodyタブをクリックして、「raw」をクリックします

Textのドロップダウンをクリックして、「JSON」をクリックします

記入欄に以下のように記入します（自分の名前とEメールを記入します）

「Send」をクリックします
ResponseにaccessTokenが来ました
そのtokenを大事に保存してください

次は、そのtokenをvariableに記入します

Simple Book APIのアイコンをクリックして、「Edit」をクリックします

Variableタブをクリックします
新しいVariableを作成します
Variableは「accessToken」
Initial Valueは「---」（他の人に本当のtokenを見られたくないので）
Current Valueは先ほど保存したtoken

続いてtokenを使って認証します

POST /ordersに戻ります
Headersタブをクリックします

「hidden」をクリック、隠し情報を解禁します

本来ならばこちらにtokenを入れるらしいですが、Postmanはもっとシンプルな認証手段を提供してくれています
Authorizationタブをクリックします

TypeにBearer Tokenをクリックします

Tokenに先ほど作ったVariable{{accessToken}}を入れます

次はPOST /ordersのBodyを作成します

Bodyタブをクリックします
「raw」を選択します
右にある青い文字をクリックして、「JSON」を選択します

そして、記入欄に以下を記入します

{
  "bookId": 1,
  "customerName": "John"
}

Random test data

ここでAPIテストのために大量なRequestを送信する必要があります
そして、できればcustomerNameは毎回違っている人がいいです

POST /ordersのタブに行き、Bodyタブをクリックします
Body内容を以下のように変えます

{
    "bookId": 1,
-   "customerName": "John"
+   "customerName": "{{$randomFullName}}"
}

また、Postman consoleから毎回の発送ログが見れます
画面の左下の「Console」をクリックします

Request Bodyの右のアイコンをクリックします（customerNameを確認するために）

これでcustomerNameの内容を確認できました

PATCH Request

次は注文情報のcustomerNameを変更します
PATCH /orders/:orderIdを使ってみようと思います

API Requesetのタブを一つ作成して、
Request nameを「Update an order」に変更し、
Request typeを「PATCH」に変更し、
URL欄に「{{baseUrl}}/orders/:orderId」に変更します

ParamsタブのorderIdに他のRequestのResponseのorderIdを記入してみます

Bodyタブをクリックします
「raw」を選択します
右にある青い文字をクリックして、「JSON」を選択します
以下のように記入します

{
  "customerName": "John {{$randomLastName}}"
}

DELETE Request

注文を削除するAPI DELETE /orders/:orderIdをやっていこうと思います

API Requesetのタブを一つ作成して、
Request nameを「Delete an order」に変更し、
Request typeを「DELETE」に変更し、
URL欄に「{{baseUrl}}/orders/:orderId」に変更します

ParamsタブのorderIdに他のRequestのResponseのorderIdを記入してみます

Bodyタブをクリックします
「none」を選択します

API Tests

今までのAPIチェックは手動的にやっています、チェック要点は以下です

Requestを送信したら

• Statusが予期の返り値（例えば：200）かを確認
• Response Bodyを確認

ここからPostman Testにより自動的にやってもらえるようにします

まずはTestタブをクリックします

そして、まずはStatusが200になっているかをチェックするテストコードを書きます

右のSnippetsから「Status Code: Code is 200」をクリックします

そして、青いボタン「Send」をクリックします

結果パネルに「Test Results」というタブが出ました

次は、Response Bodyの内容が「"status": "OK"」になっているかというテストを書きます

第一歩はResponseのテキストをJSONに変えます

const response = pm.response.json();

console.log(response);

左下のConsoleをクリック、Consoleパネルを開けます
青いボタンの「Send」をクリック、ログを確認します

ちなみにPostmanのテストの書き方はこうです
こちらは1は1と等しいというテストコードです

pm.expect(1).to.eql(1);

つまり、「"status": "OK"」のテストコードは以下です

const response = pm.response.json();

pm.test("Status should be OK", function () {
    pm.expect(response.status).to.eql("OK");
})

Postman variables

Get an order、Update an order、Delete an orderでは、ずっとPath variablesのorderIdをコピペしなければならないです
それはちょっと面倒臭いです
そこでPostman variablesを使って解決しましょう

Postman variablesはGlobalのVariableです
今まで使っていた{{baseUrl}}や{{accessToken}}はWorkspace variableです

まずは右上のEnvironment quick lookアイコンをクリックします

「Add」をクリックします

Variableに「orderId」を記入します
Current valueに現在使われているorderIdのValueを記入します

次はGet an order、Update an order、Delete an orderのorderIdのCurrent valueを{{orderId}}を記入します

Extracting data from the response

毎回操作しているbookのidを、自動的に掴むようにします

List of booksというAPIのParamsタブに、type=no-fictionのように設定します

そして、Testタブをクリックします

以下のテストコードを追加します

const response = pm.response.json()
const nonFictionBooks = response.filter((book) => book.avaliable === true);

console.log(nonFictionBooks[0])

次は、Snippetsの「Set a global variable」をクリックします

Snippetsを参照して、以下のテストコードを追加します

pm.globals.set("bookId", nonFictionBooks[0].id);

これでコーディングだけで、Global variableの設置が完了しました

Collection runner

今までは一つ一つのRequestのSendを個別にクリックしましたが
ここで一括りクリックできるように設置します

画面の右下の「Runner」をクリックします

「Simple Book API」を画面中央にドラッグします

できたらこんな感じです

APIの順序はRun Order順序と関係あるので
ちょっと調整入れます

「Register API Client」を2番目にドラッグします

そして、「Reset」をクリックします
Run Orderフィールドに最新の順序を反映させます

「Save responses」のチェックを入れておきます
「Run Simple Book API」をクリックします

これで一括り操作とテスト結果が見れるようになりました

Request execution order

今までのCollection runnerはRegister API Clientも含まれていますが
しかしあれは初回しか運行できなくて、次回以降はずっとFailedの状態になります

幸い、Register API Clienの前一つのAPIに、スキップのコードを書くことができます

1番目のAPI：API Statusのテストコードに以下のコードを追加します

postman.setNextRequest("List of books");

直接に3番目のAPI（List of books）へ飛ぶように設定します

もう一度「Register API Client」を最後にドラッグします

Delete an orderを一番最後に運行するAPIにします
Delete an orderのテストコードを追加します

postman.setNextRequest(null);

Postman monitors

左のパネルから「Monitors」をクリックします

「Create a monitor」をクリックします

Monitor nameを「Check Books API」に変更し、
Collectionから「Simple Book API」を選択します

そして、画面の右下の「Create Monitor」をクリックします

Monitorは一旦作成したから、定期的に自動的にテストを行います
そして、テストの結果をEメールでお知らせします

ここでは、一回だけMonitorをRunしてみます

Monitorの結果が見れます
こちらの「Unhealthy」は、APIに何か問題があると示しています

下方のTest resultsから認証失敗だと伝われています
その理由は、当初Collection variable作成のとき、accessTokenのInitial valueを「---」にしたからです
Monitorは、Initial valueを参照して動きますので

解決法は、accessTokenのInitial valueを本当のtokenを記入することです