wp-rest-api

WP REST API

使用するタイミング

次の作業が必要な場合に、このスキルを使用します。

• REST ルート／エンドポイントを作成または更新する
• 401／403／404 エラーや、権限／nonce の問題をデバッグする
• REST レスポンスにカスタムフィールド／メタデータを追加する
• REST 経由でカスタム投稿タイプやタクソノミーを公開する
• スキーマと引数のバリデーションを実装する
• レスポンスのリンク／埋め込み／ページネーションを調整する

必要な入力

• リポジトリのルートと対象のプラグイン／テーマ／mu-plugin（エントリーポイントへのパス）。
• 希望する名前空間とバージョン（例：my-plugin/v1）、およびルート。
• 認証方式（Cookie + nonce、アプリケーションパスワード、認証プラグインのいずれか）。
• 対象とする WordPress のバージョン制約（7.0 未満の場合は明記してください）。

手順

0) REST の使用状況を調査して場所を特定する

1. 調査を実行します。
   • node skills/wp-project-triage/scripts/detect_wp_project.mjs
2. 既存の REST の使用箇所を検索します。
   • register_rest_route
   • WP_REST_Controller
   • rest_api_init
   • show_in_rest、rest_base、rest_controller_class

サイト全体のリポジトリの場合は、コードを変更する前に対象のプラグイン／テーマを選択します。

1) 適切な方法を選ぶ

• CPT／タクソノミーを wp/v2 で公開する場合：
  • 必要に応じて、show_in_rest => true と rest_base を使用します。
  • 必要に応じて、rest_controller_class を指定します。
  • references/custom-content-types.md を読みます。
• カスタムエンドポイントの場合：
  • rest_api_init で register_rest_route() を使用します。
  • 複雑な処理には、WP_REST_Controller のサブクラスであるコントローラークラスを優先します。
  • references/routes-and-endpoints.md と references/schema.md を読みます。

2) ルートを安全に登録する（名前空間、メソッド、権限）

• 一意の名前空間 vendor/v1 を使用します。コアでない限り、wp/* は避けてください。
• 必ず permission_callback を指定します（公開エンドポイントには __return_true を使用します）。
• WP_REST_Server::READABLE/CREATABLE/EDITABLE/DELETABLE 定数を使用します。
• rest_ensure_response() または WP_REST_Response を使ってデータを返します。
• 明示的な status を指定した WP_Error を使ってエラーを返します。

references/routes-and-endpoints.md を読みます。

3) リクエスト引数を検証／サニタイズする

• type、default、required、validate_callback、sanitize_callback を指定して args を定義します。
• JSON Schema による検証を優先し、その後 rest_validate_value_from_schema、続いて rest_sanitize_value_from_schema を使用します。
• エンドポイント内で $_GET／$_POST を直接読み取らないでください。WP_REST_Request を使用します。

references/schema.md を読みます。

4) レスポンス、フィールド、リンク

• デフォルトのエンドポイントからコアフィールドを削除しないでください。フィールドを追加してください。
• 計算フィールドには register_rest_field を、メタデータには show_in_rest を指定した register_meta を使用します。
• object／array 型のメタデータには、show_in_rest.schema でスキーマを定義します。
• フィルターされていない投稿コンテンツ（例：HTML を挿入する ToC プラグイン）が必要な場合は、?context=edit を指定して content.raw にアクセスします（認証が必要です）。レスポンスを小さく保つには、_fields=content.raw も併せて指定します。
• WP_REST_Response::add_link() を使って、関連リソースへのリンクを追加します。

references/responses-and-fields.md を読みます。

5) 認証と認可

• wp-admin／JS の場合：Cookie 認証 + X-WP-Nonce（アクション wp_rest）。
• 外部クライアントの場合：アプリケーションパスワード（Basic 認証）または認証プラグイン。
• permission_callback では、単なる「ログイン済み」の確認ではなく、ケイパビリティを確認します（認可）。

references/authentication.md を読みます。

6) クライアント向けの動作（ディスカバリー、ページネーション、埋め込み）

• ディスカバリーが機能するようにします（Link ヘッダーまたは <link rel="https://api.w.org/">）。
• _fields、_embed、_method、_envelope、ページネーションヘッダーをサポートします。
• per_page の上限は 100 です。

references/discovery-and-params.md を読みます。

検証

• /wp-json/ インデックスに、指定した名前空間が含まれている。
• ルートへの OPTIONS リクエストで、スキーマが返される（指定した場合）。
• エンドポイントが想定どおりのデータを返し、権限エラーが適切に 401／403 を返す。
• show_in_rest が true の場合、CPT／タクソノミーのルートが wp/v2 に表示される。
• リポジトリの lint／テストと、必要な PHP／JS のビルド手順を実行する。

エラーの種類とデバッグ

• 404：rest_api_init が実行されない、ルートのタイプミス、またはパーマリンクが無効です（?rest_route= を使用してください）。
• 401/403：nonce／認証がない、または permission_callback が厳しすぎます。
• permission_callback がない場合の _doing_it_wrong：追加してください（公開する場合は __return_true を使用してください）。
• 無効なパラメーター：args スキーマまたは検証コールバックがない、あるいは正しくありません。
• フィールドが表示されない：show_in_rest が false、メタが登録されていない、または CPT が custom-fields をサポートしていません。

エスカレーション

バージョンサポートや動作が不明な場合は、パターンを独自に考案する前に、REST API ハンドブックとコアドキュメントを確認してください。