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

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

この記事ではPostmanを始める一助となるとよいと思い公式のドキュメントの要約をしています。

Get started

Postman first steps

Download

まずダウンロードしよう

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の結果が表示されるよ.

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を組み込めるよ