WordPressのREST APIをPostmanコレクションで管理してチームで共有する方法

WordPressのREST APIをチームで扱うなら、リクエストをPostmanの「コレクション」にまとめ、接続先や認証情報は「環境」に分けて持つのが基本の形です。この記事では、WordPress向けのコレクションの組み立て方、Application Passwordsでの認証、秘密情報を共有しない変数の使い分け、本番への誤った書き込みを防ぐ工夫、Gitでの管理とNewmanによる自動実行までを順に解説します。

なお、APIの仕様書そのもの（OpenAPI）を作る話は別記事で扱っています。この記事は「実際にリクエストを送って確認する道具を、チームでどう共有するか」に絞ります。

コレクションと環境を分けて考える

Postmanで共有するものは、大きく次の2つです。

• コレクション: リクエストの集まり。URLのパス、メソッド、ヘッダー、ボディ、テストスクリプトを持ちます。「何を送るか」の定義で、チーム全員で同じものを使います。
• 環境（Environment）: 変数の集まり。接続先のURLやユーザー名など、「どこに・誰として送るか」を持ちます。ローカル、ステージング、本番でそれぞれ用意します。

WordPressの場合、コレクション側のURLは {{baseUrl}}/wp/v2/posts のように書き、baseUrl を環境ごとに https://staging.example.com/wp-json や http://localhost:8080/wp-json に切り替えます。パーマリンク設定が「基本」のサイトでは /wp-json/ が使えず ?rest_route=/wp/v2/posts の形になるため、対象サイトの設定も最初に確認しておきます。

フォルダはエンドポイントの種類で分けると探しやすくなります。たとえば「投稿」「固定ページ」「メディア」「カスタムAPI（myapi/v1）」のように分け、フォルダ単位で認証設定を継承させると、同じ設定を何度も書かずに済みます。

認証はApplication Passwordsを使う

Postmanのような外部ツールからWordPressに認証付きでアクセスするなら、WordPress 5.6で導入されたApplication Passwords（アプリケーションパスワード）が扱いやすい方法です。

1. 各メンバーが自分のWordPressユーザーでログインし、プロフィール画面からアプリケーションパスワードを発行します（名前は「Postman 個人PC」など用途がわかるものにします）。
2. Postmanのコレクション（またはフォルダ）の認証設定で、方式をBasic認証にし、ユーザー名に {{wpUser}}、パスワードに {{wpAppPassword}} を指定します。
3. 値は各メンバーの環境にだけ入れます（次の章で説明します）。

ここで大切なのは、共有アカウントを作らず、メンバーごとに発行することです。誰かが退職したときや端末をなくしたときに、その人のアプリケーションパスワードだけを取り消せます。権限も、記事の取得だけなら「投稿者」、設定変更を試すなら「管理者」というように、必要な範囲のユーザーで発行します。

つまずきやすい点が2つあります。

• HTTPSでないと使えない: Application PasswordsはHTTPS接続のサイトで有効になります。ローカル環境では、wp-config.php で WP_ENVIRONMENT_TYPE を local にすると使えるようになります。
• Authorizationヘッダーが届かない: 一部のサーバー構成（ApacheでPHPをCGIとして動かしている場合など）では、Basic認証のヘッダーがPHPまで渡らず、401エラーになります。WordPressが生成する標準の .htaccess にはこれを補う行が含まれていますが、古い .htaccess を使い続けているサイトでは抜けていることがあります。

# WordPressの標準ブロック内にある行。無ければ RewriteEngine On の直後に追加
RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization}]

.htaccess を編集する前には、元のファイルのコピーを取っておきます。

秘密情報を共有しない変数の使い分け

Postmanでいちばん事故が起きやすいのが変数の扱いです。Postmanの変数には、チームに同期される値と、自分の端末にだけ残る値があります。画面上の表記はバージョンによって「初期値／現在値」や「共有の値／ローカルの値」などと変わってきたため（2026年10月現在）、お使いのバージョンの公式ドキュメントで、どちらが同期される側かを確認してください。

運用のルールは次のように決めておくと安全です。

• 同期される側に入れてよいもの: baseUrl、カスタム投稿タイプのスラッグ、テスト用の投稿IDなど、漏れても困らない値
• 自分の端末だけに置くもの: wpUser、wpAppPassword、外部APIのキー

さらに、パスワードやキーの変数には「secret」の種類を指定し、画面上で伏せ字にしておきます。Postmanには秘密情報を端末側で管理する仕組み（Postman Vault）も用意されているので、使える環境ならそちらに移すのも有効です。

もう1つ見落としやすいのがワークスペースの公開範囲です。Postmanのワークスペースには個人用・チーム用のほかに、誰でも閲覧できる公開ワークスペースがあります。公開ワークスペースに認証情報が残ったコレクションや環境を置いてしまう事故は実際に起きているため、共有前に範囲を確認する習慣をつけてください。

本番への書き込みを防ぐ

REST APIでは、DELETE {{baseUrl}}/wp/v2/posts/123?force=true のように、ゴミ箱を経由せずに投稿を削除するリクエストも送れます。コレクションをチームで共有すると、環境の切り替え忘れで本番のデータを書き換えてしまう危険が出てきます。

対策の1つは、コレクション全体のPre-requestスクリプトで「書き込みを許可していない環境では、GET以外を送らない」ようにすることです。

// コレクションのPre-requestスクリプト
const allowWrite = pm.environment.get('allowWrite') === 'true';
const method = pm.request.method;

if (!allowWrite && !['GET', 'HEAD', 'OPTIONS'].includes(method)) {
  console.warn('この環境では書き込み系リクエストを止めています: ' + method);
  pm.execution.skipRequest();
}

ステージングとローカルの環境にだけ allowWrite を true で用意し、本番の環境には入れません。pm.execution.skipRequest() が使えるのは比較的新しいPostmanなので、動かない場合はアプリのバージョンを確認してください。

ただし、これはあくまで操作ミスを減らすための仕組みです。本番用のアプリケーションパスワードを、書き込み権限の小さいユーザー（閲覧中心なら「購読者」や「投稿者」）で発行しておくほうが、根本的な対策になります。本番で書き込みを試す必要があるときは、事前にデータベースのバックアップを取ってください。

テストスクリプトで期待する結果を書いておく

コレクションの価値は、リクエストに「どうなれば正しいか」を添えておけることにもあります。PostmanのPost-response（以前は「Tests」と呼ばれていた欄）に、次のような確認を書いておきます。

pm.test('ステータスが200', function () {
  pm.response.to.have.status(200);
});

pm.test('投稿の配列が返る', function () {
  const json = pm.response.json();
  pm.expect(json).to.be.an('array');
  if (json.length > 0) {
    pm.expect(json[0]).to.have.property('id');
    pm.collectionVariables.set('firstPostId', json[0].id);
  }
});

最後の行のように、取得した値をコレクション変数に入れて次のリクエストで使うと、「一覧を取って、その先頭の詳細を取る」といった流れを自動で確認できます。新しく入ったメンバーも、コレクションを上から順に実行するだけでAPIの動きをつかめます。

Gitで管理し、Newmanで自動実行する

Postmanのチームワークスペースで共有するだけでも運用はできますが、コードと一緒に履歴を残したい場合は、コレクションをJSON（Collection v2.1形式）でエクスポートし、プラグインやテーマのリポジトリに置く方法があります。

my-plugin/
  postman/
    myapi.postman_collection.json
    staging.postman_environment.example.json

環境ファイルをコミットする場合は、秘密の値を空にした「見本」だけにします。実際の値はCIのシークレット機能で渡します。

コマンドラインからコレクションを実行するには、Newmanが使えます。

npm install -g newman
newman run postman/myapi.postman_collection.json \
  -e postman/staging.postman_environment.json \
  --env-var "wpAppPassword=$WP_APP_PASSWORD"

CIでステージングに対して実行すれば、プラグインの更新でAPIの応答が変わったときに気づけます。Postmanは公式のPostman CLIも提供しているので、チームの運用に合うほうを選んでください。どちらもオプションはバージョンで変わることがあるため、導入時に公式ドキュメントを確認します。

GitのJSONとPostman上のコレクションを両方更新すると、どちらが新しいかわからなくなります。「Gitを正とし、変更したらエクスポートしてコミットする」のように、どちらを正とするかを決めておいてください。

まとめ

• リクエストはコレクション、接続先と認証情報は環境に分け、{{baseUrl}} で切り替える
• 認証はメンバーごとに発行したApplication Passwordsを使い、HTTPSとAuthorizationヘッダーの受け渡しを確認する
• パスワードやキーは同期されない側の値とsecret指定で持ち、ワークスペースの公開範囲を確認する
• Pre-requestスクリプトと権限の小さいユーザーで、本番への誤った書き込みを防ぐ
• テストを添えたコレクションをGitで管理し、NewmanやPostman CLIでステージングに対して自動実行する

• WordPressのカスタムREST APIをOpenAPI（Swagger）で文書化する方法
• WordPress REST APIの認証を設定する方法