wp-rest-api

WP REST API

使用時機

當需要執行以下操作時使用此 Skill：

• 建立或更新 REST 路由/端點
• 偵錯 401/403/404 錯誤，或是權限/nonce 問題
• 在 REST 回應中新增自訂欄位/meta 資料
• 透過 REST 開放自訂文章類型 (CPT) 或分類法 (taxonomies)
• 實作 schema 與參數驗證
• 調整回應連結/內嵌 (embedding)/分頁

所需輸入

• 專案根目錄 + 目標外掛/主題/mu-plugin（進入點路徑）。
• 期望的命名空間 + 版本（例如 my-plugin/v1）與路由。
• 身份驗證模式（Cookie + nonce vs. 應用程式密碼 vs. 驗證外掛）。
• 目標 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) 選擇合適的做法

• 在 wp/v2 中開放 CPT/分類法：
  • 需要時使用 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) 安全地註冊路由（命名空間、HTTP 方法、權限）

• 使用唯一的命名空間 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；meta 資料則搭配 show_in_rest 使用 register_meta。
• 對於 object/array 類型的 meta，需在 show_in_rest.schema 中定義 schema。
• 若需要未經過濾的文章內容（例如插入 HTML 的目錄外掛），請請求 ?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（action 設為 wp_rest）。
• 針對外部用戶端：應用程式密碼 (Application Passwords / basic auth) 或驗證外掛。
• 在 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 請求會回傳 schema（有提供時）。
• 端點回傳預期的資料；權限失敗時會適當地回傳 401/403。
• 當 show_in_rest 為 true 時，CPT/分類法路由會出現在 wp/v2 下。
• 執行專案的 linter/測試以及任何 PHP/JS 建置步驟。

故障模式 / 偵錯

• 404：rest_api_init 未觸發、路由拼字錯誤，或靜態連結 (permalinks) 未開啟（可改用 ?rest_route=）。
• 401/403：缺少 nonce/身份驗證，或是 permission_callback 過於嚴格。
• 缺少 permission_callback 導致 _doing_it_wrong 警告：補上該回呼函式（若為公開端點請使用 __return_true）。
• 參數無效：缺少或不正確的 args schema，或是驗證回呼函式有誤。
• 欄位遺失：show_in_rest 設為 false、meta 未註冊，或是 CPT 缺少 custom-fields 支援。

向上通報 / 延伸查閱

如果版本支援或行為不夠明確，在自行設計新模式之前，請先查閱 REST API 手冊 (REST API Handbook) 及核心官方文件。