やさしいPostman API入門

初めてPostmanをさわる人にも優しい、Postman入門トークです。Postman を初めて見た時にわかりにくいところ（リクエストボディのフォーマットとか、リクエストの履歴とか）や、陥りがちなワナ（保存し忘れとか、認証とか）についても丁寧に解説します。実はベテラン勢も聞いてためになるかも！？Postman Tokyo Meetup 2024.1での発表資料です。

Transcript

1. All rights reserved by Postman Inc やさしい Postman API 入門 草薙 昭彦 テクノロジーエバンジェリスト #PostmanMeetup
2. テクノロジーエバンジェリスト Postman 株式会社 草薙 昭彦 @postman_japan @nagix
3. はじめての Postman - 何に使うと便利なの？ @postman_japan API のトラブルを 調査して解決 API 認証を スマートに行う API リクエスト送信と レスポンスの確認 よく使うリクエストを 整理しておく
4. Postman のはじめ方 - サインアップ @postman_japan https://identity.getpostman.com/signup まずは Postman アカウントを作成 • Postman アプリで作成したデータは Postman クラウドに保存されます • 同じ Postman アカウントを使えばどこ からでもデータにアクセスできます 必要な情報 • メールアドレス • ユーザー名（英数字とハイフン） • パスワード（7文字以上） 日本語を選べます
5. デスクトップアプリと Web アプリ @postman_japan サーバー API エンドポイント Postman デスクトップアプリ （要インストール） Postman Web アプリ （インストール不要） クライアント クライアント ブラウザー Postman クラウド ユーザーデータ リクエスト レスポンス リクエスト レスポンス
6. Postman アプリ画面 @postman_japan ヘッダー サイドバー 右サイドバー フッター ワークベンチ
7. 日本語化してみましょう ヘッダー右側の ⚙ をクリック > Settings > General > Application > Languageで日本語選択 @postman_japan
8. API リクエストの作成 @postman_japan まずはサイドバーで「新しいコレクションを作成」→ コレクションに「リクエストを追加」
9. API リクエストの作成 - GET リクエスト @postman_japan わかりやすいリクエストの名前をつける GET メソッドを選択 エンドポイントの URL を入力 保存を忘れずに リクエストはタブとして切り替えられる パラメーターなし
10. API リクエストの作成 - GET リクエスト @postman_japan クエリパラメーターあり キーと値のペアを入力 チェックを外せば無効にできる 説明はリクエストの送信には使われない キーと値は URL に反映される パラメータータブを選択
11. API リクエストの作成 - GET リクエスト @postman_japan パス変数あり 値を入力 「/:<キー名>」を URL に付けるとパス変数テーブルに反映される
12. API リクエストの作成 - POST リクエスト @postman_japan x-www-form-urlencoded 形式 ボディタブを選択 POST メソッドを選択 x-www-form-urlencoded 形式を選択 キーと値のペアを入力
13. API リクエストの作成 - POST リクエスト @postman_japan JSON 文字列形式 Raw 形式を選択 JSON を入力 「整形」はインデントや改行を整えてくれる JSON 文字列を入力
14. API リクエストの作成 - ヘッダーのカスタマイズ @postman_japan ヘッダータブを選択 キーと値のペアを入力
15. レスポンスの確認 @postman_japan 送信をクリック ボディを選択 整形を選択 レスポンスボディを見る ステータスコードを確認 レスポンスボディを見る 表示形式を指定できる レスポンスボディ内を検索
16. レスポンスの確認 @postman_japan レスポンスの詳細情報を見る ネットワーク情報 ステータスコード レスポンス時間 レスポンスサイズ
17. レスポンスの確認 @postman_japan ヘッダーを選択 レスポンスヘッダーを見る キーと値を見る ｉにマウスを合わせると説明が見られる
18. コレクションを使ってリクエストを整理する @postman_japan ワークスペース コレクション - API v2 コレクション - API v1 フォルダー - 在庫管理 フォルダー - ユーザー管理 GET リクエスト - 在庫一覧 POST リクエスト - 在庫追加 プロジェクトやバージョン毎にコレ クションを作成 フォルダーを使って階層構造を作 りリクエストを整理する
19. API 認証 @postman_japan セキュリティや利用量の追跡のために、通常は API を使うには認証が行われます。 API 認証は、API ドキュメントに書かれている方法に従って設定します。 代表的な認証の方法 Bearer トークン OAuth 2.0（Bearer トークンを利用） クライアント サービス提供者 アクセストークン API コール サービス提供者 アイデンティティプロ バイダー クライアント 連携 認証・アクセス トークン発行 サービス 情報 API コール *Bearer トークンでの認証で、どのようにアクセストークンを入手するかは様々。 OAuth 2.0 は代表例だが、JWT など他の方法もある
20. API 認証 @postman_japan API 認証については、2024年2月22日にオンラインワークショップを開催予定🚀 Bearer トークン アクセストークンを入力 Bearer トークンを選択 認証タブを選択
21. API 認証 @postman_japan OAuth 2.0 OAuth 2.0 を選択 トークンの設定を設定後、トークンを取得すると取得し たトークンが自動的に入力される
22. API のトラブルシューティングの基本 @postman_japan • ステータスコードは返ってきているか？ • ステータスコードの内容は？ 例: 認証が失敗 ステータスコードが 401。レスポンスボディにも認証されなかった旨が表示されている
23. API のトラブルシューティングの基本 @postman_japan • リクエストヘッダー、ボディ、レスポンスヘッダー、ボディを確認 例: レート制限に引っかかった ステータスコードが 403。レスポンスヘッダーの Rate-Remaining が 0 になっている。レート制限に関 するヘッダーやステータスコードは API によって異なる場合があるので注意
24. API のトラブルシューティングの基本 @postman_japan • デフォルトで非表示のリクエストヘッダーを、表示して確認 例: JSON で送るべきところをプレーンテキストで送ってしまった ステータスコードが 415。本来は Content-Type: application/json でリクエストすべきところを、Text 形式を選んでしまったので text/plain になってしまった ここが Text なので Content-Type が text/plain になった クリックすると表示に切り替わる
25. API のトラブルシューティングの基本 @postman_japan • API 履歴を確認 • 正常に動作した時のリクエストの詳細をチェックする 履歴を選択 過去に実行したリクエストを選択
26. API のトラブルシューティングの基本 @postman_japan • デフォルトでは履歴にはレスポンスヘッダーとボディは残らないが、保存するように設定することは 可能 レスポンスに保存をオンにする
27. Postman よくあるハマりポイント @postman_japan リクエストでデータが送れない → POST メソッドのボディが正しく設定されていない → API が受け付ける Content-Type をよく確認する • application/json の場合: Raw 形式で JSON を選択 • application/x-www-form-urlencoded の場合: x-www-form-urlencoded 形式を選択 • multipart/form-data の場合: form-data を選択
28. Postman よくあるハマりポイント Web アプリ利用時にリクエストが送信できない → フッターでブラウザーエージェントが選ばれていない か確認 → クラウドエージェントやデスクトップエージェント（または自動）を選択 @postman_japan エージェントって？ Web アプリでは、CORS（ドメインをまたいでリソースにアク セスできない）ポリシーのためにブラウザから直接通信がで きない場合があるため、クラウドエージェントやデスクトップ エージェントを経由した通信を行うオプションがある ブラウザーエージェント デスクトップエージェント クラウドエージェント API エンドポイント
29. ダウンロードして無料でスタート！ https://www.postman.com/downloads/ デスクトップアプリ • Windows • Mac • Linux Web アプリ • アカウント登録で同 じ機能をブラウザで も利用できる @postman_japan
30. @postman_japan ご清聴いただき、ありがとうございました