PostmanのLearning Centerを数十分で完走する


この投稿は`全世界2,800万人以上の開発者に使われているAPIプラットフォームPostmanの記事を書こう by Postman Advent Calendar 2023`の21日のカレンダーです。

この記事ではPostmanを始める一助となるとよいと思い[公式のドキュメント](https://learning.postman.com/docs/getting-started/overview/)の要約をしています。


# Get started
## Postman first steps
### Download
[まずダウンロードしよう](https://www.postman.com/downloads/)

Windows, Mac, Linuxなどあらゆるプラットフォームに対応しているよ.



### Send a request
HTTP、GraphQL、gRPCでのAPIリスエストを作成可能だよ.
レスポンスの確認もアプリケーション内で完結するよ.

#### API requests defined
HTTPのメソッド以下を使えるよ
- GET
- POST
- PATCH / PUT
- DELETE

#### Send an API request
`postman-echo.com/get`にPostmanでGETリクエストするよ.
レスポンスペインにAPIの結果が表示されるよ.

![スクリーンショット 2023-11-19 193016.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/311437/f5b15195-3055-1fe6-e11e-dd78cde6fb42.png)

#### Sign in
Postmanにサインしていないとただの軽量なAPI Clientのままだよ.
リクエストを整理したり、メンバーと共同作業したいなどPostmanを最大限活用したい場合はアカウントを作ってサインインしてね.

#### Create a workspace
ワークスペースを利用するとAPIプロジェクトの整理チームで共同作業ができるよ.
デフォルトのワークスペース以外にワークスペース以外を作成したい、共同作業用のワークスペースを用意したい場合はサインインしてね.

ワークスペースのタイプには
- Personal
  - 自分だけ見えるよ
- Private
  - 招待した人が見れるよ
- Team
  - チーム全員が見れるよ
- Public
  - すべての人が見れるよ
- Partner
  - チームと外部パートナーが見れるよ

があるよ

## Postman basics
### The Postman interface

- Header
  - ワークスペースの作成、アプリケーションの各種ができるよ
- Search Postman
  - Postman全体のチーム、PrivateAPI、コレクションなど検索できるよ
- Sidebar
  - Postmanの基本的な要素以下にアクセスできるよ
    - Collections
    - APIs
    - Environments
    - Mock servers
    - Monitors
    - Flows
    - History
- History
  - 過去のリクエストにアクセスできるよ
  - サインインすればデバイス間で同期されるよ
- Workbench
  - あらゆる作業を行うよ
  - タブでリクエストを整理できるよ
  - 共同作業者と編集が競合した場合は警告するよ
- Footer
  - 色んなツールへのアクセスができるよ
    - Hide sidebar
      - サイドバーを開閉するよ
    - Sync status
      - データ動悸されているか確認するよ
    - Find and replace
      - ワークスペースを検索するよ
    - Console
      - リクエストのデバッグができるよ
    - Postbot
      - AIボットへ質問できるよ
    - Git branch icon
      - Gitリポジトリ使用のAPIの場合、ブランチを切り替えてのソースコードの管理ができるよ
    - Runner
      - コレクションのランナーを開くよ
    - Select Postman Agent
      - デスクトップアプリをインストールしていればとりあえず気にしなくていいよ
    - Start Proxy
      - Postmanプロキシを起動するよ
    - Cookies
      - Cookieの管理をするよ
    - Trash
      - 削除されたコレクションを管理するよ
    - Two-pane view
      - 表示を1ペイン2ペインを切り替えれるよ
    - Help
      - ヘルプだよ

### The Postman Agent
取り敢えず気にしないよ

### Postbot
AIがAPIワークフローをアシストしてくれるよ

- テストを書いてくれるよ
- レスポンスをグラフやチャートでビジュアライズしてくれるよ
- APIのドキュメントをかいてくれるよ
- Postman FlowsのFQLを書いてくれるよ

### Postman VS Code extension
VS Codeに拡張機能をインストールすればVS CodeからPostmanでAPI開発できるよ

### Collaboration
アカウントを作るとPostmanを介してチームとして連携できるよ

- チームに参加するには
  - 招待メール
  - 招待リンク
  - SSO
  - SCIM
    - などがあるよ

### Syncing
あらゆる編集をアカウントを介して各デバイスに同期するよ

- サインアウトするとローカルから同期データを削除するよ
- サインインするとクラウドから同期するよ
- リロードすると自動的に最新verを取得するよ
- 同時にサインインできるのは業務 and 個人PC and 携帯電話の3台だよ

### Lightweight API Client
 
- Postmanはサインインしなくても
  - HTTP
  - WebSocket
  - gRPC
  - GraphQL
    - のクライアントととして使えるよ
 
### Scratch Pad
非推奨でサポートされないよ

## Installation and configure
PostmanはデスクトップとWebアプリ版があるよ
デスクトップ版はWin/Mac/Linuxに対応しているよ
VsCodeの拡張機能もあるよ

### Use Postman behind a firewall
PostmanのインフラはAWS上にあるよ
ファイヤーウォールから以下のドメインがWebSocket接続できるようにしてね

- *.getPostman.com
- *.postman.co
- *.pstmn.io
- *.postman.com

- Postman web app - WebSocket connection
  - https://bifrost-web-v10.gw.postman.com
  - https://bifrost-web-public-v10.gw.postman.com
  - https://bifrost-web-v10.gw.postman.co
- Postman desktop app - HTTP connections
  - https://bifrost-https-v10.gw.postman.com
  - https://bifrost-premium-https-v10.gw.postman.com

### Settings
Postmanの諸々を設定できるよ
⌘+Comma (,) or Ctrl+Comma (,)で起動してね

- General
  - リクエスト、UIなどのカスタマイズができるよ
    - Request
      - リクエストのパラメータをトリミングできるよ
      - SSL証明書をチェック有無を設定できるよ
      - タイムアウトの時間を設定できるよ
      - ダウンロードする最大の応答サイズを設定できる
    - Working directory
      - request時のバイナリファイル、request bodyを保存するディレクトリを指定できるよ
    - Themes
      - Postmanテーマを選択できるよ
    - Shortcuts
      - ショートカットキーをカスタマイズできるよ
    - Data
      - Postmanデータを一括エクスポート、インポートできるよ
    - Add-ons
      - Newmanをダウンロードできるよ
    - Certificates
      - 証明書の管理ができるよ
    - Connected accounts
      - サードパーティのサービスで Postman を認証するためのアカウントやトークンを管理できます
    - Proxy
      - プロキシ設定ができるよ
    - App updates
      - Postmanをアップデートできるよ
    - About
      - Postmanの現在のバージョンを確認できるよ
      - お役立ちリンクが確認できるよ

### Account management
アカウントを持つと作業内容の同期、バックアップができるよ
異なるマシンからアクセスできるよ
APIプロジェクトで他の人と連携できるよ

- Signing up for a Postman account
  - Email or Googleアカウントでログインできるよ
  - 名前、役割など入力するよ
  - プロフィールを共同作業者が閲覧できるよ
    - カスタマイズできるよ
  - Creating or joining a team
    - チームを作るかチームに参加するか決めれるよ

- Signing in to Postman
  - Google アカウントでSSOできるよ
  - 非アクティブの状態でも30日間サインインを保持できるよ
  - 二要素認証できるよ
  - Linking your acount to Postman
    - Emailアドレスで作成したアカウントもSSOに関連付けることができるよ
  - Switching between accounts
    - 複数のアカウントで同時にログインできるよ

- Updating your account settings
  - メールアドレス、パスワードなどアカウント情報を管理できるよ
  - Changing your email address
    - 無料チームまたは有料チームのメンバーであればアカウントに関連付けされたメールアドレスを変更できるよ 
    - SCIMが有効なチームのメンバーの場合、管理者に問い合わせてね
  - Resetting your password
    - Professional or Basic or Freeのプランを利用場合アカウント設定ページから変更できるよ
    - サインイン前の場合、サインページから復旧できるよ
  - Setting up two-factor authentication
    - 設定から2FA設定できるよ
  - Turning off two-factor authentication
    - 2FAはいつでも無効にできるよ
  - Deleting your account
    - 削除すると復旧できないよ
      - 同期されたデータは削除されるよ
    - 削除前にチームから退会してね
  - Updating your notification preferences
    - 設定 > 通知で通知ON設定ができるよ
    - 項目ごとに通知の設定ができるよ
    - Slackと連携できるよ
  - Managing your active sessions
    - アクティブなセッションの管理ができるよ
    - Postmanにログインしているデバイスが確認できるよ
    - セッションを取り消すことができるよ
  - Upgrading your account
    - アカウントをアップグレードすることができるよ
  - Account security policies and standards
    - Postmanは個人データを守るあらゆる技術を使ってるよ

### Profile customization
プロフィールをカスタマイズできるよ
写真、ソーシャルメディアへのリンク、略歴などあるよ

### Proxy server configuration
デフォルトではシステムに設定されたプロキシを使うよ
プロキシの設定をカスタマイズできるよ

## Import and export data

- Data import and export
  - Postmanはコレクション、環境、グローバル、データダンプを含むデータをインポートおよびエクスポートできるよ
  - Gitリポジトリ、New Relic、cURLなどを用いたインポートもできるよ
- Data import method
  - Postmanにデータインポートするにはファイル、フォルダ、cURLなどの手段があるよ
  - もうコレクションv1フォーマットはサポートしてないよ、インポートしようとするとエラーになるよ
v1からv2にコンバートしてからインポートしてね
- Git Import
  - GitHub、Bitbuket、GitLab、Azure DevOpsからインポートできるよ
  - ローカルリポジトリでもクラウドにホストされているリモートリポジトリからでもインポートできるよ
- New Relic import
  - New RelicからAPIキーを取得すればインポートできるよ
- Insomnia import
  - InsomniaのリクエストやコレクションをHTTP Archive(HAR)としてエクスポートしてPostmanにインポートできるよ
- cURL commnad Import
  - cURLでインポートできるよ
- Swagger API import
  - Swaggerで作成されたOpenAPI仕様のAPIををインポートできるよ
- Data export
  - PostmanのデータをJSONでエクスポートできるよ
  - これを他の人と共有したりNewmanで使用することもできるよ

## Send requests
- Request authorization
  - Postmanはリクエストと同時に認証でデータをリクエストのヘッダ、ボディ、パラメータに含むことができるよ
- Authentication setup
  - リクエストを開いた状態でAuthorizationタブで認証のタイプを選択できるよ
- Public API authorization
  - Postmanを通じて簡単な認証を提供するパブリックAPIが増えているよ
    - Stripe
    - Open AI
    - Notion
    - Spotify
- Authorization Type
  - サポートしている認可のタイプは以下
    - No Auth
    - API Key
    - Bearer token
    - JWT bearer
    - Basic auth
    - Digest auth
    - OAuth 1.0
    - OAuth 2.0
    - Hawk authentication
    - AWS Signature
    - NTLM authentication
    - Akamai EdgeGrid
    - ASAP (Atlassian)

### API response structure
PostmanはAPIを正確に視覚化するよレスポンスビューアーがあるよ
APIレスポンスはレスポンスボディ、ヘッダー、クッキー、HTTPステータスだよ
ネットワーク情報、レスポンスサイズ、レスポンスタイム、セキュリティ警告の詳細も表示するよ

- Response body
  - Pretty
    - JSONやXMLのレスポンスを見やすく整形するよ
  - Raw
    - レスポンスがミニファイされるよ
  - Preview
    - レスポンスをレンダリングするよ
    - HTMLのエラーを返すよ、デバッグに使ってね
  - Visualize
    - レスポンスをビジュアライズすることができるよ
- Cookies
  - サーバから送信されたクッキーを確認できるよ
- Headers
  - ヘッダが表示されるよ
- Test results
  - APIリクエストにテストスクリプトが用意してある場合にテストの結果が表示されるよ
- Network information
  - ネットワークの情報を表示するよ
  - SSL verification errors
    - SSLの検証に失敗した場合、エラーメッセージが表示されるよ
- Response code
  - APIのレスポンスコードが表示されるよ
- Response Time
  - サーバからレスポンスが返ってくる時間を計算するよ
- Response size
  - レスポンスのサイズを表示するよ
- Saving responses
  - APIリクエストのレスポンスを保存できるよ
    - JSONファイルに書き出せるよ
- Viewing security warnings
  - APIのセキュリティリスク警告を示すよ
    - 警告をオフにできるよ

### Group requests in Collections
コレクションにリクエストをまとめることでワークスペースを整理できるよ

### Store values in variables
変数を保存しておくとコレクション、環境、リクエスト、テストスクリプトで再利用できるよ
チームメイトとの連携、ダイナミックなワークフローのセットアップに役立つよ
本番環境、テスト環境などと変数を使い分けることができるよ

- Variable scopes
  - Global variables
    - グローバル変数はワークスペース全体で使用できるよ
  - Collection variables
    - コレクション内のリクエスト全体で使用できるよ
  - Environment variables
    - 選択中の環境で使用できるよ
  - Data variables
    - CSVやJSONから取得するよ
    - Newman、Collection Runnerでコレクションを実行する時に定義できるよ
  - Local variables
    - リクエストスクリプトでアクセスされる一時変数だよ
- Initial and current values
  - 変数には初期値を設定できるよ
    - 共同作業する時に便利だよ
  - 変数には`current value`が設定できるよ
    - 変更した場合は永続化されないよ
- Variable Type
  - default
    - プレーンテキストだよ
  - Secret
    - マスキングされているよ
- Defining variables
  - あらゆるスコープの変数を定義できるよ
- Using variables
  - `{{}}`を用いて変数を参照することができるよ
- Sharing and persisting data
  - 変数はinitialとcurrentがあるよ
  - Persistオプションを指定するとcurrentがpushされるよ
    - currentがinitialに更新されるよ
- Fixing unresolved variables
  - リクエストに未定義な変数が使われている場合、フラグを立てるよ

### Group values in Environments
- Create and use envrioments
  - 環境は1つ以上の変数のセットだよ
  - 環境を切り替えてリクエストなどに適用できるよ
- Set environment variables
  - 環境へは変数を設定できるよ
    - initial、currentを設定できるよ
    - 削除できるよ
- Manage team environments
  - Postmanでチームとして作業していると
    - データ共有できるよ
    - 変数を共有できるよ
    - APIキーやパスワードなど機密データの可視性を管理・共有できるよ

### Visualize request responses
ビジュアライザーはリクエストレスポンスの視覚的な表現を設定できるよ
レスポンスデータを理解しやすい表示にできるよ

### Create request response examples
exampleを作成することでリクエストのあらゆる挙動に対応することができるよ
リクエストのバリエーションを用意することができるよ

### Create and capture cookies
任意のクッキーすることができるよ


### Other
- Postmanは以下にも対応しているよ
  - GraphQL
  - gRPC
  - WebSocket
  - MQTT
  - SOAP

## Write scripts
リクエストの事前にスクリプト(pre-script)を実行したり、テストスクリプトを実行できたりするよ
pre-scriptとテストスクリプトは非同期だよ、逐次実行したい場合はコールバック関数を使ってね

## Postman Collections
- Postman Collectionは保存されたリクエストのグループだよ
- 送信されたリクエストは全て履歴タブに表示されるよ、履歴タブから再利用ができるよ
- リクエストの実行を自動化できるよ
  - 実行をスケジュールできるよ、結果をレポートで受け取ることができるよ
- Webhookを使ってPostmanのCollectionを実行できるよ
- APIのパフォーマンスをテストできるよ
- ライブコレクションを使うとコレクションを最新状態に保てるよ
- PostmanにNewmanというCLIツールもあるよ

## Postman Flows
ワークスペース内でリクエストを連鎖、データの処理、実際のワークフローを作成できるよ

## Postman CLI
Postmanには`Postman CLI`があるよ
手動でコレクションを実行、テストできるよ、CI/CD上で利用することもできるよ

Newmanとの比較は以下の通りだよ
|Postman CLI|Newman|
|:--:|:--:|
|Created by Postman|Created by Postman|
|Maintained and supported by Postman|Open source; supported by community contributions|
|Supports collection runs|Supports collection runs|
|Automatically sends collection run results to Postman by default|Supports ingesting run results to Postman using a reporter|
|Package is signed by Postman|Package is signed by Postman|
|Distributed as a downloadable package|Distributed on npm|
|Downloadable programmatically|Downloadable programmatically|
|Not available as a library|available as a library|
|Supports sign in and sign out|Doesn't supports sign in and sign out|
|Checks API definition against configured API Governance and API Security rules|Doesn't check API definition against configured API Governance and API Security rules|

## Collaborate
- チーム内でコラボレーションできるよ
- 組織内のユーザがチームへの参加をリクエストできるよ
- チームのワークスペースを作成して共同作業できるよ

- Team discovery
  - オンボーディングを簡素にできるよ
  - ドメイン認証されたメールアドレスを持つユーザで参加リクエストできるよ
- Tead workspaces
  - APIやコレクションなどで共同作業できるよ
- Team discussions
  - コレクション、フォルダ、リクエストなどコメントを用いたディスカッションできるよ

- ロールを設定してアクセスレベルを定義できるよ
- 組織にあったグループを作成してユーザを参加させることができるよ
- バージョン管理できるよ 
- チーム外部に公開するコレクションを管理できるよ
- APIを公開することができるよ
  - 2000万人以上のユーザと共有できるよ

## Design and develop APIs
- WSDLやOpenAPIの定義ファイルなどからAPIを定義できるよ
- APIを`Aamazon API Gateway`や`Azure API Management`などにデプロイできるよ
- コレクションの結果をSlack、Splunkなどに送信できるよ
- New RelicやDataDogとも連携できるよ
- モックサーバを作成してAPIをシミュレーㇳすることもできるよ

## Document APIs
- コレクションとAPIのドキュメント自動で作成するよ
- ドキュメントには以下を含むよ
  - メソッド
  - 認可タイプ
  - URL
  - リクエスト
    - パラメータ
    - ヘッダ
      - キー
      - 値
    - ボディ
  - レスポンスの構造
- ドキュメントは公開できるよ
  - カスタムドメインでホストできるよ

## Monitor APIs
- APIの状態を可視化するよ
- APIへのアクセスを静的なIPからに設定することができるよ

## Administration
- スーパユーザがいるよ
  - チームの作成ができるよ
  - メンバー、パートナー、ゲストの管理ができるよ
  - 監査ログにアクセスできるよ
- SSOできるよ
- SCIMをサポートしているよ
- ドメインキャプチャによって組織に関連するアカウントを統合するよ

## Billing
- Postmanは独自の請求プロセスを用意しているよ
- 不明点はサポートに問い合わせてね

## API Governance
- 統制されたルールを適用できるよ
- 一貫性のあるAPIを作成できるよ

## Reports
- 利用状況のレポートを生成できるよ
  - これらの状況を把握できるよ
    - テスト
    - ドキュメント
    - モニタリングカバレッジ

## Developer resources
- Postmanの開発者リソースを利用できます
- GitHubでオープンソースプロジェクトを利用し貢献もできるよ

## Integrations
- AWSやSlackなどにPostmanを組み込めるよ