wp-rest-api-development

WordPress REST API 開発スキル

概要

WordPress のプラグイン、テーマ、カスタムコードを対象に、REST API を体系的にレビューします。基本原則： すべてのルートに、明確な契約、明示的な認可、検証済みの入力、予測可能な出力が必要です。レビューでは、ルート登録、コントローラーパターン、リクエストの解析、スキーマと引数の検証、レスポンスの形式、キャッシュへの影響、互換性に関する懸念を確認します。必要に応じて、行番号、重要度ラベル、BAD/GOOD のコード例を添えて指摘事項を報告します。

使用する場面

次の場合に使用します：

• register_rest_route() の使用状況をレビューする
• カスタム API エンドポイントやコントローラークラスを監査する
• permission_callback のロジックを確認する
• WP_REST_Request の入力処理を検証する
• レスポンスの形式、ステータスコード、スキーマをレビューする
• ヘッドレスアプリやブロック駆動型アプリ向けに、バージョン管理されたエンドポイントを設計する

次の場合には使用しないでください：

• REST に重点を置かない一般的なプラグインアーキテクチャの確認（wp-plugin-development を使用）
• プラグイン全体を対象としたセキュリティのみのレビュー（wp-security-review を使用）
• WooCommerce エンドポイントの全面的なレビュー（WC 固有の場合は wp-woocommerce-dev を使用）
• GraphQL 固有のガイダンス

コードレビューワークフロー

1. REST の使用箇所を特定する

   • プラグインのブートストラップ内にあるルートコールバック
   • WP_REST_Controller を拡張するコントローラークラス
   • ヘッドレスフロントエンドとの連携
   • 管理者専用の内部 API の使用

2. まずルート登録を確認する

   • 名前空間とバージョンの形式
   • HTTP メソッドが操作の意図に合っているか
   • permission_callback が設定され、具体的であるか
   • リクエスト検証用の args 定義

3. リクエスト処理をレビューする

   • 生のグローバル変数ではなく、$request->get_param() または型付きゲッターを使用する
   • すべてのユーザー入力を検証し、サニタイズする
   • 不正な形式の入力は、意味のある WP_Error で拒否する

4. レスポンス設計をレビューする

   • 一貫したレスポンス形式
   • 適切なステータスコード
   • 有用な場合は rest_ensure_response() を使用する
   • 内部情報を漏えいさせない

5. CRITICAL/WARNING/INFO に該当するパターンを確認する

   • CRITICAL： permission_callback の欠落、__return_true を使った書き込みルート、生のグローバル変数、安全でない DB クエリ
   • WARNING： スキーマの不整合、弱い入力検証、レスポンス形式の混在、ページネーション情報の欠落
   • INFO： コントローラークラスの使用、スキーマの再利用、バージョン管理の整理を検討できる

6. 相互参照を添えて報告する

   • 認証または nonce の問題が中心の場合は、/wp-sec-review を提案する
   • ルートのロジックがプラグインアーキテクチャに大きく関わる場合は、/wp-plugin-review を提案する

ファイルタイプ別の確認項目

ルート登録（register_rest_route）

• CRITICAL：permission_callback の欠落
• CRITICAL：書き込みエンドポイントでの 'permission_callback' => '__return_true'
• WARNING：名前空間にバージョン部分がない
• WARNING：rest_api_init の外でルートを登録している
• INFO：コントローラーメソッドを使うべきインラインコールバックの重複

権限コールバック

• CRITICAL：非公開データに対する権限チェックの欠落
• WARNING：管理者向けの操作でコールバックが常に true を返す
• WARNING：ユーザー固有のリソースに対する所有者チェックの欠落
• INFO：繰り返し使われる権限ロジックを一元化できる

リクエスト引数と検証

• CRITICAL：エンドポイントのコールバック内で生の $_GET/$_POST を使用している
• WARNING：sanitize_callback または validate_callback の欠落
• WARNING：既知の値に対する enum/形式の制約がない
• INFO：再利用可能な項目スキーマを定義できる

レスポンス処理

• WARNING：ルート間で成功レスポンスの形式が混在している
• WARNING：REST コールバック内でレスポンスデータを返さずに wp_send_json() を使用している
• INFO：ヘッダーやステータスを制御するために WP_REST_Response を使用できる

すばやく検出するための検索パターン（API-21）

REST API をすばやくスキャンするには、以下の rg コマンドを使用します。重要度別に整理しています。

CRITICAL パターン

# register_rest_route candidates
rg -n "register_rest_route\s*\(" . -g '*.php'

# permission_callback returning true
rg -n "permission_callback.*__return_true" . -g '*.php'

# Raw superglobals inside REST callbacks
rg -n "\$_GET|\$_POST|\$_REQUEST" . -g '*.php'

WARNING パターン

# WP_REST_Request usage without obvious validation helpers
rg -n "WP_REST_Request|get_param\s*\(" . -g '*.php'

# REST callbacks using wp_send_json
rg -n "wp_send_json|wp_send_json_success|wp_send_json_error" . -g '*.php'

# Route namespaces to inspect for versioning
rg -n "register_rest_route\s*\(\s*['\"][^'\"]+" . -g '*.php'

INFO パターン

# WP_REST_Controller classes
rg -n "extends\s+WP_REST_Controller" . -g '*.php'

# rest_ensure_response usage
rg -n "rest_ensure_response|new\s+WP_REST_Response" . -g '*.php'

参考ファイル

• references/route-patterns.md - ルート登録、コントローラーの構成、名前空間の設計
• references/schema-and-auth-guide.md - Args スキーマ、権限コールバック、入力検証、レスポンス設計

出力形式（API-23）

各指摘には、次の内容を含めてください。

1. 重要度：CRITICAL、WARNING、INFO のいずれか
2. ファイルと行番号
3. 問題の概要
4. WordPress REST API の動作にとって重要な理由
5. 推奨される修正

問題が見つからない場合は、その旨を明確に伝え、テストの不足、スキーマドキュメントの不整合、バージョニング戦略の限定性など、残っている課題があれば記載してください。