wp-rest-api

WP REST API

使用する場面

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

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

必要な入力

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

手順

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_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 ハンドブックとコアドキュメントを確認してください。