繁體中文（台灣）
  • RESTful
  • REST
  • RPC
  • API
  • architecture
  • API design

只有POST？讓我們結束這場荒謬的 API 設計爭論

破解「只有POST」API的迷思，解釋為什麼這源於對API設計原則的誤解，並闡明RESTful和RPC架構風格的適當用途。

Yijun
Yijun
Developer

最近，有關是否使用「只有POST」設計API的討論引起了我的注意。在深入研究這場爭論後，我發現人們爭論的問題不僅毫無意義，還暴露了許多開發人員對API設計本質的誤解。今天，讓我們深入探討API設計的核心思想，看看為什麼這場爭論根本不應該存在。

「只有POST」的誤解

那些倡導使用「只有POST」來取代RESTful API規範的開發者顯然沒有掌握API設計中最重要的一點。他們的論點通常包括：

  1. 簡化設計：一種方法可以處理所有事情
  2. 安全性：POST參數不出現在URL中
  3. 靈活性：POST可以發送任何數據結構

乍看之下，這些論點似乎有一些道理。但事實上，這種看法是將HTTP方法的選擇與API設計風格混淆了，這是兩個不同層次的問題。POST只是HTTP協議的一種方法，而REST是一種API設計風格。

API 設計的本質

在討論具體的API風格之前，我們需要了解API設計的核心目的。好的API應該是：

  1. 清晰且可理解：其他開發者（包括你未來的自己）應該能夠直觀地理解每個端點的目的
  2. 一致性：遵循某些規範以減少學習成本
  3. 可擴展性：能夠輕鬆進行版本控制和功能擴展
  4. 高效性：考慮性能和資源利用方面的效率

RESTful API：不僅僅是HTTP方法的選擇

RESTful API 是眾多API設計風格中的一種，專注於資源及對資源的操作。我們以一個簡單的博客系統為例，看看RESTful API 是如何設計的：

  1. 獲取所有文章：

  2. 獲取特定文章：

  3. 創建新文章：

  4. 更新文章：

  5. 刪除文章：

在這個例子中，我們可以看到：

  • API 是圍繞「文章」資源設計的
  • 不同的HTTP方法用來代表不同的操作
  • URL結構清晰，指示正在操作的資源

這種設計方法使API更直觀和自我解釋，開發者容易理解每個端點的功能。

RPC：理解「只有POST」背後的API風格

RPC（遠程過程調用）風格API設計的目標是使遠程服務調用看起來像調用本地函數一樣簡單。

有趣的是，那些倡導「只有POST」的人可能沒有意識到他們其實是在描述RPC風格。

相較於RESTful APIs，RPC 更注重於操作本身而非資源。這就是為什麼RPC風格的API通常使用「動詞+名詞」形式，例如 getProduct(productId) 或 createUser(userData)。

在許多RPC實現中，所有操作通常都是通過POST請求發送到同一個端點，具體操作和參數在請求正文中指定。這就是為什麼「只有POST」的想法其實更接近RPC而非REST的原因。

例如，一個基於HTTP的RPC風格「獲取產品」請求可能如下所示：

現代RPC框架，如gRPC，提供更強大和高效的實現。讓我們以此為例展示RPC風格：

首先，我們定義服務和消息格式（使用 Protocol Buffers）：

然後，在Node.js客戶端中使用此服務，就像調用本地函數一樣簡單：

在這個RPC風格的例子中，我們可以看到：

  1. 服務定義清楚列出了所有可用的操作（在這個簡化範例中，GetArticle 和 CreateArticle）。
  2. 每個操作都有明確定義的請求和回應類型。
  3. 客戶端代碼看起來像是在調用本地異步函數，使用 await 等待結果進一步掩蓋了網絡通信的複雜性。
  4. 無需手動構建HTTP請求或解析JSON響應。

即使底層仍可能使用HTTP/2作為傳輸協議，RPC框架（如gRPC）向開發者提供了一個抽象層，使遠程調用看起來和感覺都像是本地函數調用。

因此，我們可以看到關於「只有POST」和RESTful API的大部分辯論實質上應該是關於這兩種API風格的討論：REST和RPC。然而，關鍵是要認識到這兩種風格各有其適用場景，選擇應根據項目的具體需求，而不是個人喜好。

REST vs RPC：沒有絕對的優劣

既然我們了解了REST和RPC的區別，讓我們看看它們各自的適用場景：

  1. REST 適合於：
    • 以資源為導向的應用（例如內容管理系統、博客平台、電子商務網站）
    • 需要良好緩存支持的場景（GET請求自然可緩存）
    • 想利用HTTP語義的專案（如使用適當的狀態碼）
    • 需要良好發現性和自我描述的公開API
  2. RPC 適合於：
    • 以動作為導向的應用（例如複雜數據處理操作、工作流控制）
    • 需要高性能低延遲的系統（例如實時交易系統）
    • 內部微服務之間的通信（可能需要更靈活的參數傳遞）
    • 當操作不能簡單地映射到CRUD（創建、讀取、更新、刪除）操作時

風格的選擇應基於你的具體需求。在某些情況下，你甚至可以在同一體系中使用這兩種風格的混合來滿足不同部份的需求。

總結

  1. API設計的核心在於清晰、一致、可擴展且高效，而非堅持使用某種特定的方法或風格。
  2. RESTful和RPC都是成熟的API設計範式。兩者之間的選擇應基於專案需求，而非個人喜好。
  3. 如果你決定使用「只有POST」，那麼請根據RPC風格設計你的API。像RESTful一樣，它也是業界常用的API規範，但應用於適當的場景。
  4. 不要被表面的技術細節所迷惑，真正重要的是你的API能否有效地服務於你的用戶和業務需求。
  5. 在設計API時，花更多時間思考你的資源模型、業務邏輯和用戶需求，而不是執著於該使用哪個HTTP方法。

讓我們將注意力從這些無意義的爭論中移開，專注於設計真正優秀的API。畢竟，技術是為了解決問題，而不是製造問題。

免費試用 Logto Cloud