別再寫出連自己都看不懂的 API！資深工程師的 WordPress REST API 設計原則終極指南

嗨，我是浪花科技的資深工程師 Eric。寫程式這麼多年，我看過最混亂的戰場，不是佈滿 `!important` 的 CSS 檔案，也不是巢狀超過十層的迴圈，而是那些缺乏靈魂、沒有章法的 API 設計。前端工程師一臉茫然，iOS 和 Android 的同事各自為政，最後大家都把矛頭指向你——那個寫後端 API 的傢伙。

「欸，這個 `get_user_data_and_posts_v2_final` 是在幹嘛的？」、「為什麼刪除文章要用 GET？」「回傳的資料一下是 `userID`，一下是 `user_id`，是在玩我嗎？」這些對話是不是很熟悉？如果你點頭如搗蒜，那這篇文章就是你的救贖。今天，我們不談高深的演算法，只專注在一件最根本、卻也最常被忽略的事情：API 設計原則（REST + JSON）。尤其是在 WordPress 這個強大的生態系裡，學會如何設計出優雅、一致且可預測的 REST API，將會讓你的開發效率和團隊合作體驗直接起飛。

API 到底是什麼？為什麼你的 WordPress 專案迫切需要它？

先來個工程師的老派比喻吧。想像一下你去餐廳吃飯，你（客戶端，Client）不會自己跑到廚房去跟廚師（伺服器，Server）說你要一客牛排，三分熟，配蘑菇醬。你會透過服務生（API，應用程式介面）來點餐。你只需要告訴服務生你的「請求」（Request），他會用餐廳規定的格式把訂單傳給廚房，廚房處理完後，再由服務生把牛排（回應，Response）送到你桌上。

API 就是這個「服務生」。它定義了不同軟體組件之間如何溝通、交換資料的規則和協定。在 WordPress 的世界裡，這意味著：

• 前後端分離（Headless WordPress）： 你可以用 WordPress 當作純粹的內容管理後台，然後用 React、Vue 或 Svelte 這些現代前端框架打造超炫的互動介面，所有資料都透過 REST API 來交換。
• 手機 App 整合： 你的官方 App 需要顯示最新的文章或商品？沒問題，直接呼叫你設計好的 API 端點 (Endpoint) 就行了。
• 第三方服務串接： 想把 WooCommerce 的訂單資料同步到 ERP 系統？或是把文章自動發布到社群平台？這一切都離不開 API。

簡單來說，一個好的 API 能讓你的 WordPress 網站從一個單純的「網站」進化成一個強大的「資料中心」，擁有無限的擴展可能性。而要打造一個好的 API，我們就必須認識它的設計靈魂——REST。

RESTful API 設計六大黃金原則：不只是口號，更是架構的靈魂

很多人聽到 REST (Representational State Transfer) 就覺得很學術，其實它不是什麼嚴格的協定，而是一種架構風格、一組設計原則。遵循這些原則的 API，我們就稱之為「RESTful API」。它就像是 API 設計界的君子協定，大家都照著玩，溝通成本就會降到最低。

1. 主從式架構 (Client-Server)

這很直觀，客戶端（前端、App）和伺服器（你的 WordPress 後端）是分開的。客戶端負責使用者介面和體驗，伺服器負責儲存和處理資料。兩者透過 API 溝通。這種分離讓雙方可以獨立開發、迭代，只要 API 這份「合約」不變，大家就相安無事。

2. 無狀態 (Stateless)

這是 REST 最核心也最常被誤解的原則。無狀態意味著每一次從客戶端發出的請求，都必須包含伺服器理解和處理該請求所需的所有資訊。伺服器不能儲存任何關於客戶端會話 (Session) 的狀態。白話文就是：伺服器是金魚腦，它處理完你的請求就忘了你是誰。你下一次請求，必須再把身分證明（例如 API 金鑰或 JWT Token）帶上。

這樣做有什麼好處？極佳的擴展性！ 因為伺服器不需要維護狀態，你可以輕易地增加好幾台伺服器來做負載平衡，任何一台伺服器都能處理任何請求，系統會變得非常強健。

3. 可快取 (Cacheable)

效能！效能！效能！好的 API 設計必須考慮到效能。REST 允許伺服器在回應中明確標示該回應是否可以被快取。客戶端或中間的代理伺服器（如 CDN）就可以把這些回應暫存起來，下次同樣的請求可以直接使用快取，大幅減少對後端伺服器的壓力，也加快了終端用戶的載入速度。這和 WordPress 的物件快取 有異曲同工之妙。

4. 分層系統 (Layered System)

客戶端不需要知道它到底在跟誰說話。它可能直接連到應用程式伺服器，也可能中間隔了好幾層，像是負載平衡器、快取伺服器、API 閘道器等等。這種分層架構讓系統更有彈性，你可以隨時在中間加入新的層次來增強安全性或效能，而不用修改客戶端的程式碼。

5. 統一介面 (Uniform Interface)

這是讓 REST API 變得簡單又強大的關鍵。它包含幾個子原則：

• 資源導向 (Resource-based)： API 的設計應該圍繞著「資源」。例如「文章」、「商品」、「使用者」。URL 的設計應該是名詞，而不是動詞。例如：
  /wp-json/my-app/v1/products (取得所有商品)
  /wp-json/my-app/v1/products/123 (取得 ID 為 123 的商品)
• 透過表示層操作資源 (Manipulation of resources through representations)： 當客戶端拿到一個資源的表示（通常是 JSON 格式），它就擁有了足夠的資訊去修改或刪除這個資源。
• 自描述訊息 (Self-descriptive messages)： 每個請求和回應都應該包含足夠的資訊讓對方理解。例如，請求頭中的 `Content-Type: application/json` 告訴伺服器我送的是 JSON；回應中的狀態碼 (Status Code) 告訴客戶端操作的結果（例如 200 OK, 404 Not Found, 500 Internal Server Error）。

6. 應需編碼 (Code on demand，非必要)

這條比較少見，它允許伺服器將可執行的程式碼（例如 JavaScript）傳給客戶端，暫時擴充客戶端的功能。但在現代前後端分離的架構下，這條原則相對沒那麼重要。

用對 HTTP 動詞，讓你的 API 會說話

既然我們的 URL 都是名詞（資源），那要怎麼表示對資源的操作呢？答案就是 HTTP 方法 (Methods)，或稱 HTTP 動詞：

• GET： 讀取資源。例如 `GET /products` 是取得商品列表，`GET /products/123` 是取得單一商品。這是安全的、冪等的 (Idempotent) 操作，不管你呼叫幾次，結果都一樣。
• POST： 新增資源。例如 `POST /products` 就是新增一項商品，資料會放在請求的主體 (Request Body) 裡。
• PUT / PATCH： 更新資源。`PUT` 是完整替換，`PATCH` 是部分更新。例如 `PUT /products/123` 會用你提供的資料完整覆蓋掉原本的商品資訊。實務上 `PATCH` 更常用，也更有彈性。
• DELETE： 刪除資源。例如 `DELETE /products/123` 就是刪除這項商品。

拜託，千萬不要再設計出 `POST /getProduct` 或 `GET /deleteProduct` 這種 API 了，這會讓你的同事在心裡默默地問候你。善用 HTTP 動詞，你的 API 會變得非常直觀且語意清晰。

WordPress 實戰：用 `register_rest_route` 打造你的第一個客製化 API 端點

講了這麼多理論，是時候來點硬核的了。我們來動手用 WordPress 內建的函式，打造一個遵循 REST 原則的 API 端點。假設我們有一個自訂文章類型 (Custom Post Type) 叫做 `book`，我們想建立一個 API 來取得書籍列表。

把下面這段程式碼加到你的主題 `functions.php` 或是一個自訂外掛中：

<?php
add_action( 'rest_api_init', function () {
  register_rest_route( 'my-app/v1', '/books', array(
    'methods'  => 'GET',
    'callback' => 'my_awesome_get_books_api',
    'permission_callback' => '__return_true', // 警告：僅供示範，實際上線需做權限檢查！
  ) );
} );

function my_awesome_get_books_api( WP_REST_Request $request ) {
  $args = array(
    'post_type'      => 'book',
    'posts_per_page' => 10,
    'post_status'    => 'publish',
  );

  $query = new WP_Query( $args );

  if ( ! $query->have_posts() ) {
    // 如果沒有書籍，回傳 404 Not Found
    return new WP_REST_Response( array(
        'status'  => 404,
        'message' => 'No books found.',
        'data'    => array(),
    ), 404 );
  }

  $books = array();
  while ( $query->have_posts() ) {
    $query->the_post();
    $books[] = array(
      'id'      => get_the_ID(),
      'title'   => get_the_title(),
      'author'  => get_post_meta( get_the_ID(), 'book_author', true ),
    );
  }

  wp_reset_postdata();

  // 成功時，回傳標準格式的 JSON
  $response = new WP_REST_Response( array(
      'status'  => 200,
      'message' => 'Books retrieved successfully.',
      'data'    => $books,
  ), 200 );

  return $response;
}
?>

讓我們拆解一下這段程式碼：

1. 我們掛載 `rest_api_init` 這個 action hook 來註冊我們的路由。
2. `register_rest_route` 接受三個參數：命名空間 (namespace)、路由 (route) 和一個設定陣列。
3. 在設定陣列中：
   • `methods`：我們指定了 `GET`，符合 RESTful 讀取資源的原則。
   • `callback`：當這個 API 被呼叫時，要執行的函式。
   • `permission_callback`：這是最重要的安全防線！ 這裡我們用了 `__return_true` 讓所有人都能存取，但在真實專案中，你必須在這裡檢查使用者是否有足夠的權限，例如使用 `current_user_can()`。這和 Nonces 的安全概念一樣重要。
4. 在 `my_awesome_get_books_api` 函式中，我們用 `WP_Query` 取得資料，整理成乾淨的陣列，最後用 `WP_REST_Response` 這個 class 來回傳一個標準的 JSON 物件，並附上正確的 HTTP 狀態碼。

現在，你只要訪問 `https://your-domain.com/wp-json/my-app/v1/books`，就能看到一個結構清晰、語意明確的 JSON 回應了。這就是一個好的 API 的起點。

好的 API 設計，是專案成功的基石

打造一個好的 API，遠不只是讓程式能跑而已。它是一門關於溝通、架構和未來性的藝術。一個設計精良的 RESTful API，能讓你的團隊成員（甚至是幾個月後的你自己）快速上手，減少溝通成本，提高開發效率，並且讓你的系統更容易維護和擴展。

記住，API 是給「人」用的，不論是前端工程師還是第三方開發者。多花一點時間思考你的資源命名、HTTP 動詞的選擇、以及 JSON 回應的結構，這些投入在未來絕對會加倍回報給你。別再讓你的 API 成為團隊的溝通障礙了，讓它成為你專案中最穩固、最可靠的橋樑吧！

延伸閱讀

• 解鎖 WordPress 的無限可能：資深工程師帶你深入 REST API 的黑魔法世界
• 不只是文章和頁面！解放 WordPress 潛能，用 Custom Post Type 打造獨一無二的網站結構
• 你的表單安全嗎？揭開 WordPress Nonces 的神秘面紗，杜絕 CSRF 攻擊的終極防線！

如果你對於如何在你的 WordPress 專案中導入更複雜的 API 設計、或是需要專業的系統架構規劃感到困惑，浪花科技的團隊擁有豐富的實戰經驗，能協助你打造高效、安全且易於維護的系統。歡迎點擊這裡與我們聯繫，讓我們的專家為你的專案賦能！