FSWP API 開發者 是做什麼的？
基礎（始終套用）： fswp-developer/references/lean-coding.md（精簡撰寫、優先重複使用）、fswp-developer/references/coding-standards.md（編碼標準、文件、國際化、無障礙）以及 fswp-security-engineer（輸入、輸出、授權）。
官方參考：REST API 手冊（fswp-developer/references/official-docs.md）。fswp-security-engineer 中的安全規則適用於每一條路由。
註冊路由
function vp_register_routes() {
register_rest_route( 'vendor-prefix/v1', '/items/(?P<id>\d+)', array(
'methods' => WP_REST_Server::READABLE,
'callback' => 'vp_get_item',
'permission_callback' => function ( WP_REST_Request $r ) {
return current_user_can( 'edit_post', (int) $r['id'] );
},
'args' => array(
'id' => array( 'type' => 'integer', 'required' => true, 'sanitize_callback' => 'absint' ),
),
) );
}
add_action( 'rest_api_init', 'vp_register_routes' );
規則
- 命名空間與版本：
vendor-prefix/v1。絕不在核心的wp/v2命名空間中註冊。 permission_callback為強制項目。 回傳能力檢查結果，而不僅是登入狀態。僅在資料確實為公開時使用__return_true，並附上註解說明原因。當請求中包含 ID 時，檢查物件層級的存取權限（edit_post、所有權）。- 宣告
args，包含type、required、enum、minimum/maximum、validate_callback和sanitize_callback。即使經過驗證，請求仍不可信任；請使用經過型別轉換的$request->get_param()值。 - 使用
rest_ensure_response()回傳資料；錯誤則使用new WP_Error( 'vp_code', __( 'Message', 'text-domain' ), array( 'status' => 404 ) )。使用準確的狀態碼（400 無效、401 未驗證、403 禁止、404 找不到、409 衝突、413 過大）。 - Schema： 實作
get_item_schema()（或schema回呼），以便用戶端和索引能描述資源；使用prepare_item_for_response()塑造回應。 - 集合： 支援
page/per_page並設定硬上限，設定X-WP-Total和X-WP-TotalPages，且絕不回傳無限制的清單。 - 絕不回傳 機密資訊、密碼雜湊、原始選項或其他使用者的私人資料。
- 控制器： 若路由超過兩三條，請擴充
WP_REST_Controller（register_routes、get_items、get_item、create_item、每個方法的權限檢查）並僅註冊該類別一次。 - 公開核心物件： 自訂文章類型與分類法使用
'show_in_rest' => true（以及rest_base）；中繼資料使用register_meta()/register_post_meta()並設定'show_in_rest' => true，同時提供 schema 和auth_callback。 - 快取與效能：
GET處理常式應輕量；快取耗費資源的結果（fswp-performance-engineer）；避免在迴圈中進行查詢。
認證
| 用戶端 | 方法 |
|---|---|
| 同站 JS（管理後台、區塊、前端） | 使用帶有 X-WP-Nonce 標頭的 Cookie 認證（wp_create_nonce( 'wp_rest' )，或 wp_localize_script / @wordpress/api-fetch 自動添加） |
| 外部伺服器或應用程式 | 透過 HTTPS 使用應用程式密碼，或經審查的 OAuth 外掛 |
| 公開讀取 | 無需認證，僅限資料為公開時 |
Nonce 不能取代能力檢查。CORS：請勿在已認證的路由上開啟 Access-Control-Allow-Origin: *。
用戶端
在區塊和後台畫面中使用 @wordpress/api-fetch。根據 code 和 message 處理錯誤，而非解析文字。
Abilities API
一個用於註冊離散、機器可讀能力的核心 API（名稱、輸入 schema、輸出 schema、權限檢查、執行回呼），工具和 AI 代理可進行探索與呼叫。此 API 較新：請在開發者文件中確認最低 WordPress 版本及確切的函數名稱，然後再使用（搜尋「Abilities API」）。僅在 PRD 需要代理可呼叫的函數時使用；一般的用戶端-伺服器呼叫使用純 REST 即可。
註冊 ability 時：
- 先在文件中規定的鉤子上註冊類別，再註冊 ability。
- 為其提供輸入和輸出的 JSON Schemas，以及一個檢查真實能力的
permission_callback。 - 誠實設定安全註解：唯讀 abilities 不得執行寫入操作，具破壞性的必須標記。回呼在標記為唯讀的情況下執行寫入即為缺陷，
fswp-reviewer會將其視為缺陷。 - 僅將應該可遠端呼叫的項目透過 REST 公開。
稽核與驗證程序：references/abilities.md。
若要提議哪些現有端點應轉換為 abilities，請列出每個路由及其方法、目前權限檢查、副作用以及建議的註解；在獲得核准前，請勿註冊任何內容。