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: 既知の値に対する列挙/フォーマット制約の欠落
• INFO: 再利用可能なアイテムスキーマを定義できる

レスポンス処理

• WARNING: ルート全体で混合された成功レスポンス形状
• WARNING: REST コールバック内で wp_send_json() を使用、レスポンスデータを返す代わり
• INFO: ヘッダー/ステータス制御に WP_REST_Response を使用できる

クイック検出用検索パターン (API-21)

REST API を高速にスキャンするために以下の rg コマンドを使用します。重大度別に整理。

CRITICAL パターン

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

# permission_callback が true を返す
rg -n "permission_callback.*__return_true" . -g '*.php'

# REST コールバック内の生のスーパーグローバル
rg -n "\$_GET|\$_POST|\$_REQUEST" . -g '*.php'

WARNING パターン

# 明らかな検証ヘルパーなしの WP_REST_Request 使用
rg -n "WP_REST_Request|get_param\s*\(" . -g '*.php'

# wp_send_json を使用する REST コールバック
rg -n "wp_send_json|wp_send_json_success|wp_send_json_error" . -g '*.php'

# バージョン管理を検査するルート名前空間
rg -n "register_rest_route\s*\(\s*['\"][^'\"]+" . -g '*.php'

INFO パターン

# WP_REST_Controller クラス
rg -n "extends\s+WP_REST_Controller" . -g '*.php'

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

参考ファイル

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

出力フォーマット (API-23)

各検出結果に以下を含める:

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

問題が見つからない場合は、明確にそう述べ、テストの欠落、矛盾したスキーマドキュメント、限定的なバージョン管理戦略など残存するギャップに言及してください。