POSTMAN BEST PRACTICES

ツールチェーンとの統合

Building quality APIs has never been more important. At Postman, we believe being API-first is the key to innovation in the AI era. We built Postman Best Practices to share the foundational ideas Postman is built on and enable you to do your best work.

ツールチェーンが分断されていると、API仕様とコードの内容が一致しなくなり、テストの失敗がチャットのやり取りに埋もれ、デバッグのために複数のシステムを行き来する必要が生じます。

この章では、あなたにNative Gitを紹介し、あなたスタックのGitHub、Slack、Teams、JiraなどのツールとPostmanを統合する方法を示します。これにより、あなたが作業の流れに乗れて見落としを逃さないようにしています。

Abhinav Asthana

Abhinav Asthana

Postman CEO and Co-founder

Ankit Sobti

Ankit Sobti

Postman Field CTO and Co-founder

API開発は、決して単独で行われるものではありません。多くのチームはすでに、GitHubを使ったバージョン管理、SlackやMicrosoft Teamsを使ったコミュニケーション、そしてJiraを使った課題管理のワークフローを確立しています。しかし、これらのツールチェーンが連携していない場合、API開発は断片化しがちです。仕様とコードの整合性が崩れ、テストの失敗通知はチャットの中に埋もれ、デバッグの際には複数のシステムを行き来して原因を突き止めなければならなくなります。

Postman は、既存の開発ツールと直接統合し、API設計・テスト・コラボレーションをコードの変更、チームのコミュニケーション、プロジェクト管理と常に同期させます。これらの統合は、単一アプリケーション向けのアプリ専用APIにも、複数チームで利用される再利用可能APIにも対応しています。

Git統合：APIとコードを同期

APIの仕様とコードを別々のシステムで管理していると、両者の内容が徐々にずれ、不完全なドキュメントやコントラクトの破損、統合エラーが発生することがあります。開発と設計を密接に連携させることで、こうした不整合を防ぎ、常に最新の状態を維持することができます。

このガイドは、アプリ専用API と社内向け再利用可能APIのどちらにも有効です。

GitHubとのツール統合。イラスト。

Native Git

Native Gitは、PostmanデスクトップアプリをローカルのGitリポジトリに直接接続します。コレクション、API仕様、環境、モックなど、すべてのPostmanアセットをコードとともに/postmanディレクトリ内のファイルとして保存できます。Native Gitの詳細は、ドキュメントをご覧ください。

設定ガイド：

  1. Postman desktop appを開き、ワークスペースに移動します。
  2. ワークスペースメニューから［Connect Repository］を選択し、Gitプロバイダーへのアクセスを許可します。
  3. 画面の指示に従って、ローカルGitリポジトリのルートディレクトリを選択します。
  4. Postmanによって/postmanディレクトリが作成され、既存のワークスペースのアセットがその中に保存されます。
  5. /postmanディレクトリをリポジトリにコミットし、Postmanアセットをコードと一緒にバージョン管理します。

開発ワークフロー：

  1. APIに変更を加える前に、Gitでフィーチャーブランチを作成します。
  2. Postman desktop appを開きます。ワークスペースには、チェックアウトしているブランチの内容が自動的に反映されます。
  3. Postmanでコレクション、仕様、環境を変更します。変更内容はローカルファイルシステムに直接保存されます。
  4. Postmanの変更とコードの変更を同じプルリクエストに含めてコミットし、APIの設計と実装を同期した状態に保ちます。

重要：Native Gitは「Local View」でのみ動作します。Postmanアセットへの変更は、ブランチをプッシュして変更がリモートリポジトリにマージされるまで、Postman Cloudには同期されません。

推奨プラクティス：

  • /postmanディレクトリはリポジトリのルートに配置し、すべての開発者が、コードとその内容を記述するPostmanアセットを一緒に見つけられるようにします。
  • Postmanアセットへの変更もコードと同じように扱います。コレクションやAPI仕様への変更は、マージする前にPRでのレビューを必須にします。
  • ローカル環境の値（base_url、APIキーなど）は各開発者のマシンのローカル環境に保存し、機密情報を/postmanディレクトリにコミットしないようにします。環境の管理についての詳細は、ドキュメントをご覧ください。

GitHub統合

GitHub統合では、Postman Cloudを介してPostmanコレクションをGitHubリポジトリに接続できます。Postman desktop appを使用しなくても、自動的にバックアップして同期できます。

GitHub統合は、次の用途に使用できます。

  • コレクションを保存するたびに、GitHubリポジトリ内のpostman/フォルダーにバックアップします。
  • コレクションへの変更を、対象のブランチ（mainやdevelopなど）に同期します。
  • Postmanコレクションへの変更がコミットされたときに、github-actionsを通じてCI/CDワークフローを実行します。
開発全体を通じてテストを実行。イラスト。
Microsoft Teamsとのツール統合イラスト。

設定ガイド：

  1. ワークスペースの統合メニューから、GitHubリポジトリをPostmanコレクションに接続します。
  2. コレクションファイルを保存するリポジトリ、ブランチ、ディレクトリを選択します。
  3. 保存するたびに同期するか、必要なときに同期するかを選択します。
  4. Postman CLIをCI/CDパイプラインに統合し、プルリクエストごとにコレクションテストを実行します。

推奨プラクティス：

  • 新しい機能を開発するときはコレクションをフォークし、イテレーションを重ねている間もメインのコレクションを安定した状態に保ちます。
  • GitHubのブランチ保護ルールを設定し、Postmanコレクションのテストに合格することをマージの必須条件にします。
  • Postmanのビジュアル差分ツールを使用して、プルリクエスト内でコード変更とAPI変更を並行してレビューします。

SlackおよびMicrosoft Teamsとの統合：API変更を常に把握する

APIの重要な更新は、メール通知で見逃されたり、チームがあまり確認しない確認しないダッシュボードに埋もれがちです。破壊的な変更に気づかないまま開発が進んだり、APIの問題にすぐ対応できない状況が続くと、開発の勢いが鈍り、課題が次々に増えていきます。

SlackおよびMicrosoft Teamsとのツール統合イラスト。
Slack統合の設定。イラスト。

このガイドは、アプリ専用API と社内向け再利用可能API のどちらにも有効です。

実践ガイド

Postmanワークスペースをチームのコミュニケーションツールに接続し、APIの変更通知、モニターアラート、コラボレーションリクエストなどを、チームが日常的に作業している場所で共有できるようにします。

ワークスペース通知の設定
  • PostmanワークスペースをSlackやMicrosoft Teamsの関連チャンネルに接続する。
  • どのアクティビティを通知するかを選択し、チャンネルに送信する通知を絞り込む。
  • Workspace Updates 機能を利用して、重要なAPI変更をサブスクライブしているチャンネルに直接通知する。
  • チームのAPI利用者が、依存しているAPIの最新情報を得られるよう、関連チャンネルを購読できるようにする。
コンテキスト共有とサポート依頼
  • コレクション、リクエスト、レスポンス、ワークスペース、コメントなど、Postman内の要素へのリンクをコピーしてチャンネルで共有する。
  • APIの問題を共有する際は、関連するテスト結果や背景情報も添えて投稿し、メンバーが的確にサポートできるようにする。
  • チャンネル内から返信できるだけでなく、Postmanに戻って直接コラボレーションできる双方向のやり取りを有効化する。
  • スレッド形式の会話を使って、APIに関するディスカッションを整理し、後から検索しやすくする。
モニターアラートの設定
  • トリガーされた時、失敗した時、またはパフォーマンス低下を検知した時に、モニターが該当チャンネルへ通知が届くように設定する。
  • アラートの種類に応じてチャンネルを分ける（例：重大障害はオンコールチームへ、パフォーマンス問題はエンジニアリングチームへ）。
  • 個人通知を有効化し、アクセスリクエストやアクションをSlack経由で直接処理できるようにする。
  • 通知には対応に必要な情報を含めることで、チームが迅速に行動できるようにする。

推奨プラクティス

  • 一般的な開発ディスカッションとは分けて、API更新専用のチャンネルを使用する。
  • チームの対応が必要な実行可能イベントに絞ることで、可視性とノイズのバランスを取る。
  • APIの問題を共有する際は、関連コレクションへのリンクやテスト結果を添付する。
  • チームチャンネルで共有されたAPIアラートに対して、確認・対応の手順や責任者を明確に定義しておく。
OpenAPI機能。

Jira統合：APIに関する作業をプロジェクトのワークフローに組み込む

API開発がプロジェクト管理システムの外で行われていると重要な作業が関係者から見えなくなり、優先順位のずれや、技術的な取り組みとビジネス目標とのつながりが失われてしまいます。

このガイドは、アプリ専用API だけでなく、社内向けやパートナー向けの再利用可能API にも適用できます。

プロジェクトワークフロー。

実践ガイド

PostmanをJiraプロジェクトに直接接続し、API開発の進捗管理、バグ報告、機能開発の連携をシームレスに行えるワークフローを構築します。

Jiraプロジェクトの接続：
  • PostmanワークスペースとJira Cloudを統合する。
  • プロジェクトマッピングを設定し、API関連の課題が適切なJiraプロジェクトに自動ルーティングされるようにする。
  • 課題の説明欄にAPI特有の情報を記録できるよう、カスタムフィールドマッピングを設定する。
コンテキストを含めた課題の作成：
  • 失敗したAPIリクエストや想定外のレスポンスから、直接、Jiraの課題を生成する。
  • リクエストの詳細、レスポンスデータ、環境情報を課題の説明に自動で含める。
  • 関連するコレクションやテスト結果をリンクし、デバッグに必要な完全なコンテキストを提供する。
Postman内で進捗を追跡：
  • Postmanのリクエストパネル上でJira課題のステータスを直接確認できる。
  • ツールを切り替えることなく、課題解決の進捗をモニタリングできる。
  • APIの問題が特定・解決され次第、課題ステータスを更新して最新の状態を保つ。
Jiraクラウドに追加。

推奨プラクティス

  • API関連の課題テンプレートをJiraで作成し、デバッグに必要な基本情報を一貫して記録できるようにする。
  • プロジェクトワークフロー内で適切に処理されるよう、API課題の優先度を判断する明確な基準を設定する。
  • API作業がエンジニアリングチームとプロダクトチームの両方から可視化できるように、Jiraプロジェクトを構成する。
  • API課題が解決済みで、十分にテストされたことを明示できるワークフローを運用する。
  • Agent Modeを使って、JiraからGitHubへのマージを自動化する。

ヒント：Agent Modeを使って、APIに関する情報をすべて含むJiraチケットを作成しましょう。エンドポイントの障害を担当チームにエスカレーションする必要がある場合、Agent Modeを使えば、デバッグに必要な情報をすべて含むJiraチケットの下書きを1回の操作で作成できます。プロンプト：「@POST /api/v2/refunds が501を返しています。エンドポイントの詳細、OpenAPI仕様で定義されている想定レスポンススキーマ、再現手順を含むJiraチケットをバックエンドチーム向けに作成してください。」

使いながら理解するのが一番です。GitHubリポジトリをコレクションに接続する、Slack通知を設定する、またはJiraの課題追跡を設定する。