API 不是能動就好！資深工程師的 WordPress API 設計宣言：打造溝通無礙、可擴展的數位橋樑
嗨，我是浪花科技的 Eric。身為一個整天跟程式碼打交道的工程師，我看過各式各樣的 API。有些 API 像是一本條理分明的說明書，讓你一用就上手；但有些，說真的，簡直像一場災難，充滿了各種猜謎和陷阱，光是串接就搞得你一個頭兩個大。這也是為什麼我今天想來囉嗦一下，聊聊一個很多 WordPress 開發者容易忽略，卻又極其重要的主題：WordPress API 設計原則（REST + JSON）。
很多人會覺得：「API 不就是能動、能把資料丟出來就好了嗎？」如果你只是做個自用的小工具，或許是吧。但當你的 WordPress 網站需要跟其他系統（例如手機 App、第三方服務、自動化工具 n8n）溝通，或是你正在開發一個準備給別人用的外掛時，你的 API 就成了你的「產品門面」。一個設計混亂、沒有章法的 API，不只會讓串接的開發者想砸電腦，更會嚴重影響你專案的擴展性和未來的維護成本。這可不是危言聳聽，一個爛 API 挖的坑，遲早都得自己含淚跳下去填。
為什麼我們需要為 WordPress API 制定「設計原則」？
想像一下，你走進一間圖書館，所有的書都亂七八糟地堆在地上，沒有分類、沒有索引。你想找一本書，除了從頭翻到尾，別無他法。這就是一個沒有設計原則的 API 給人的感覺。
API（Application Programming Interface）的本質，就是一套「溝通的契約」。它定義了你的 WordPress 網站如何與外部世界對話。一個好的 API 設計，就像是為這場對話制定了清晰、一致的語法和規則，讓任何「說著同樣語言」的開發者都能快速理解並參與進來。
好的 API 設計能帶來什麼好處？
- 降低學習曲線： 當你的 API 遵循業界公認的標準（例如 RESTful 風格），其他開發者就能憑藉既有經驗快速上手，不需要再花大把時間通靈、猜測你的 API 是怎麼運作的。
- 提升開發效率： 清晰的 API 結構和一致的命名規則，讓前端或串接方可以更專注於業務邏輯，而不是浪費時間在搞懂你的 API 到底在回傳什麼。
- 增強系統的穩定性與可擴展性： 一個有良好版本控制和錯誤處理機制的 API，在未來新增功能或修改時，不容易「牽一髮而動全身」，導致舊有的串接全部掛掉。
- 便於維護與除錯： 當問題發生時，一個結構化的 API 能讓你更快地定位問題來源。到底是請求端送錯資料，還是伺服器端出了問題，一目了然。
說到底，投資時間在 API 設計上，就是投資在專案的未來。今天多花一小時思考 API 的結構，明天就能省下十小時的除錯與溝通成本。
WordPress API 的基石：擁抱 RESTful 架構
當我們談論現代網頁 API 設計，幾乎離不開 REST（Representational State Transfer）。別被這個專有名詞嚇到，它不是一個嚴格的協定，而是一組設計風格或架構約束。WordPress 的核心 REST API 就是基於這個理念打造的，我們在自訂 API 時，也應該遵循這些原則。
原則一：萬物皆「資源」（Resources）
在 REST 的世界裡，所有東西都是「資源」，例如一篇文章、一個使用者、一張訂單。而我們透過 URL（Uniform Resource Locator）來定位這些資源。
一個重要的觀念是：URL 應該使用名詞，而不是動詞。
- (X) 不好的設計：
/wp-json/my-api/v1/getProducts、/wp-json/my-api/v1/createProduct - (O) 好的設計：
/wp-json/my-api/v1/products
我們用同一個 URL /products 來代表「產品」這個資源集合。那要怎麼區分是「取得」還是「新增」呢？這就要靠下一個原則了。
原則二：用 HTTP 動詞（Verbs）表達操作
RESTful API 會善用 HTTP 本身就定義好的方法（動詞）來表達對資源的操作，而不是把操作寫在 URL 裡。
GET /products：取得所有產品列表。GET /products/123：取得 ID 為 123 的單一產品。POST /products：新增一筆產品資料（請求的 body 中會包含產品資訊）。PUT /products/123或PATCH /products/123：更新 ID 為 123 的產品資料（PUT 為完整替換，PATCH 為部分更新）。DELETE /products/123：刪除 ID 為 123 的產品。
你看，同樣一個 /products 端點，透過不同的 HTTP 動詞，就能實現完整的 CRUD (Create, Read, Update, Delete) 操作。這讓我們的 API 變得非常直觀且有語意。
原則三：無狀態（Stateless）
這點對工程師來說非常重要。無狀態意味著伺服器不會儲存任何關於客戶端上一次請求的資訊。每一次的請求，都必須包含所有必要的資訊，讓伺服器能夠獨立處理這次請求。這就像跟金魚說話，你每次都得把前因後果再講一遍。
聽起來好像很麻煩，但這卻是 API 能夠輕鬆擴展（Scale）的關鍵。因為任何一台伺服器都能處理任何一個請求，不需要同步彼此的「記憶」。在 WordPress 中，我們通常透過 Nonces 或應用程式密碼（Application Passwords）這類機制，在每一次請求中驗證使用者身份，來實現無狀態的認證。
溝通的語言：把 JSON 說得漂亮又清楚
如果說 RESTful 是 API 的文法，那 JSON（JavaScript Object Notation）就是我們選擇的詞彙。它輕量、易讀，並且是 JavaScript 的原生格式，這讓它成為現代 API 的首選。但同樣是說 JSON，有人說得像詩一樣優雅，有人卻說得像火星文一樣難懂。
1. 命名一致性是基本禮貌
WordPress 核心習慣用蛇式命名法（snake_case），例如 post_title、author_id。而 JavaScript 生態圈則偏好駝峰式命名法（camelCase），例如 postTitle、authorId。你選哪一個？說真的，都可以，但最重要的是「保持一致」！ 不要一下用蛇式，一下用駝峰式，這會讓串接的人精神錯亂。
2. 提供結構化、可預期的回應
一個好的 JSON 回應，應該是結構清晰、層次分明的。避免把所有資料都扁平化地放在第一層。
(X) 不好的 JSON 結構：
{
"id": 123,
"product_name": "神奇小藥丸",
"author_id": 1,
"author_name": "Eric",
"author_email": "eric@roamer-tech.com"
}
(O) 好的 JSON 結構：
{
"id": 123,
"name": "神奇小藥丸",
"author": {
"id": 1,
"name": "Eric",
"email": "eric@roamer-tech.com"
}
}
把作者相關的資訊包在一個 author 物件裡，結構是不是清晰多了？
3. 優雅地處理錯誤
API 最忌諱的就是「沉默的失敗」。當請求出錯時，不要只回傳一個通用的 500 伺服器錯誤，而是要給出一個明確的 JSON 錯誤訊息，告訴對方到底發生了什麼事。WordPress 的 WP_Error 和 WP_REST_Response 就是你的好朋友。
在你的 API callback 函式中，你可以這樣做：
function my_awesome_api_callback( WP_REST_Request $request ) {
$product_id = $request->get_param('id');
if ( empty( $product_id ) ) {
// 產生一個 WP_Error 物件
$error = new WP_Error(
'no_id_provided',
'請提供產品 ID。',
array( 'status' => 400 ) // Bad Request
);
return new WP_REST_Response( $error );
}
// ... 處理正常的邏輯 ...
$data = array( 'message' => '成功！' );
return new WP_REST_Response( $data, 200 );
}
當 ID 沒提供時，API 會回傳一個 HTTP 400 狀態碼，以及像下面這樣的 JSON，讓前端可以清楚知道錯誤原因並提示使用者。
{
"code": "no_id_provided",
"message": "請提供產品 ID。",
"data": {
"status": 400
}
}
進階但重要的設計原則
當你掌握了以上基礎，可以開始考慮一些更進階的原則，讓你的 API 晉升到「企業級」水準。
- 版本控制 (Versioning): 在 URL 中加入版本號，例如
/wp-json/my-plugin/v1/products。當未來你需要對 API 做出重大修改（可能不相容舊版）時，你可以推出/v2版本，而不會影響到還在使用/v1的舊用戶。這是專業 API 的標配！ - 善用查詢參數進行篩選、排序與分頁: 當資源列表很長時，一次回傳所有資料是場災難。你應該允許使用者透過查詢參數來客製化結果，例如：
GET /products?status=publish&orderby=date&per_page=10&page=2。 - HATEOAS (Hypermedia as the Engine of Application State): 這個聽起來很嚇人，但概念很簡單。就是在你的 API 回應中，附上相關操作的連結。例如，當你取得一筆訂單時，同時告訴你可以「取消這筆訂單」的 API 連結是什麼。WordPress 核心 API 回應中的
_links物件就是這個概念的實現，它讓你的 API 具備了自我探索的能力。
結論：API 是溝通的藝術，而不只是技術
寫出一個「能動」的 API 很容易，但設計一個「好用、好懂、好維護」的 API，卻是一門需要刻意練習的藝術。它考驗的不只是你的程式能力，更是你的同理心——你是否能站在 API 使用者的角度思考？
下次當你在 WordPress 中建立自訂端點（Custom Endpoint）時，請務必停下來想一想這些 API 設計原則（REST + JSON）。把你的 API 當成一個需要精心打磨的產品，你會發現，這份前期的投入，將在未來為你和你的團隊省下無數的麻煩與時間。這就是一個資深工程師的囉嗦，但相信我，這絕對值得。
如果你正在規劃需要複雜 API 串接的 WordPress 專案，或是對現有的 API 架構感到頭痛，卻不知從何下手優化，歡迎與浪花科技的團隊聊聊。我們樂於分享我們的經驗，幫助你打造出穩定、高效且易於合作的數位橋樑。
延伸閱讀
- WordPress REST API 宇宙大爆炸：從零開始打造你的第一個自訂端點！
- 你的 WordPress 正在大開後門嗎？資深工程師的 Webhook 設計與安全驗證終極指南
- API 狂call被鎖帳號？資深工程師教你 WordPress API 串接的優雅之道：Rate Limit 與重試機制全解析
常見問題 (FAQ)
Q1: 對於 API 設計新手來說，最重要的原則是什麼？
A1: 一致性！無論是你的 URL 結構（永遠用名詞）、HTTP 動詞的使用，還是 JSON 的命名風格（snake_case 或 camelCase），請從頭到尾保持一致。一個可預測的 API 就是一個好的開始，這能大幅降低串接方的學習成本。
Q2: 為什麼 API 版本控制（Versioning）這麼重要？
A2: 因為需求是會變的。當你的 API 上線並被多個服務使用後，你很可能會需要修改它的結構或行為。如果沒有版本控制，任何「破壞性」的改動都會讓所有正在使用它的服務立刻癱瘓。透過在 URL 中加入版本號（如 /v1/, /v2/），你可以在不影響舊用戶的情況下，安全地發布新版 API，讓大家有時間遷移。
Q3: 在 WordPress REST API 中，處理錯誤的最佳實踐是什麼？
A3: 絕對不要只回傳一個通用的錯誤訊息或讓請求逾時。最好的做法是使用 WordPress 內建的 WP_Error 物件來包裹你的錯誤資訊，並透過 WP_REST_Response 回傳。這樣你可以自訂一個錯誤碼（code）、易於理解的錯誤訊息（message），並設定一個精確的 HTTP 狀態碼（例如 400 Bad Request, 401 Unauthorized, 404 Not Found），讓串接方能以程式化的方式處理錯誤。
