RESTful Web API 心得

在Web API之中，其中一種被廣範使用的是 RESTful (REST = Representational State Transfer)

Representational State Transfer (REST) 是一種軟體架構，它對 API 的運作方式施加了條件。REST 最初是作為管理複雜網路 (如網際網路) 上的通訊指導方針而建立。您可以使用以 REST 為基礎的架構，來支援大規模的高效能和可靠的通訊。您可以輕鬆實作和修改，為任何 API 系統提供可視性和跨平台可移植性。
API 開發人員可以使用若干不同的架構來設計 API。遵循 REST 架構風格的 API 稱為 REST API。實作 REST 架構的 Web 服務稱為 RESTful Web 服務。術語 RESTful API 通常是指 RESTful Web API。但是，您可以互換使用術語 REST API 和 RESTful API。

什麼是 RESTful API？– RESTful API 介紹 – AWS (amazon.com)

因為實在太常用了，所以隨便在網上找找就有很多資訊。以下是一些參考：

• REST - Wikipedia
• 什麼是 RESTful API？– RESTful API 介紹 – AWS (amazon.com)
• 一文带你看懂什么是 RESTful API？ (redhat.com)
• What is a REST API? | IBM
• RESTful API 为何成为顶流 API 架构风格？ | Apache APISIX® -- Cloud-Native API Gateway
• 浅谈三种API设计风格RPC、REST、GraphQL - 知乎 (zhihu.com)

盡量跟隨 Best Practice

• REST API URI Naming Conventions and Best Practices (restfulapi.net)
• Web API design best practices - Azure Architecture Center | Microsoft Learn

六個(REST 架構風格)原則

1. 統一介面 (Uniform interface)
2. 客戶伺服器分離模式 (或稱 主從模式) (Client-Server)：任何一個客戶端與伺服器都是可替換的。
3. 無狀態 (Statelessness)
4. 分層系統 (Layered system)：客戶端不知道他聯絡的是不是最終伺服器。
5. 可快取性 (Cacheability)
6. 隨需編碼 (Code on demand) [可選]：伺服器可以將能力擴充到客戶端，如果客戶端可以執行的話。這個功能是可選擇的。

統一介面的四個級別

• 級別0：以資源為基礎，每個資源都可以通過URI訪問到。
• 級別1：通過客戶端(Client)可以修改原資源的狀態
• 級別2：自描述性的回應 (Self-descriptive messages), See:
  • Self-descriptive messages - Hands-On RESTful API Design Patterns and Best Practices [Book] (oreilly.com)
  • How To Make A Self-Descriptive Enterprise API | Nordic APIs |
• 級別3：實現 HATEOAS

要點

1. 很適合存取資源(Resource)，即是對紀錄的操作。例如是交易紀錄、產品資料、甚至是一個狀態。所以大多對應 CRUD (Create, Read, Update, Delete) 操作
2. 不適合非存取資源的操作，例如執行或觸發一個動作(Action or Method or Function)等（如 setAlarm 這類），這一種API應該屬RPC API (詳見：RPC 與 REST – API 架構之間的區別 – AWS (amazon.com)）
3. RESTful API不是標準，只是指引(Guideline)，所以沒有固定的實踐方式。雖然如此還需盡量跟從上面的五個重點，尤其是 「統一介面」、「無狀態」和「可快取性」
4. 先定義API規格 (API Specification) 後才編程
5. 使用Swagger(或類似的工具)做技術文檔
6. 盡可能做到級別2

API 設計的注意事項

Endpoint

• 使用Endpoint區分不同的Resource - 即一個Endpoint對應一個資源
• 一個Endpoint 可以有不同的操作方式，如 CRUD 操作
• Endpoint 是有請求(Request)有回應(Response)
• 必須清楚描述

HTTP 請求 (Request)

URI (Unique resource identifier)

URI就是一個資源的識別符號，隨著URI代表了URL和URN，技術文件多會用 URI 而非 URL，雖然很多時候大部份人都認為 URL 和 URI是一樣的。總的來講，URI的格式是這樣：

URI = scheme ":" ["//" authority] path ["?" query] ["#" fragment]

URI的命名法則

• 命名選字要嚴緊些，可參考：
  • REST API URI Naming Conventions and Best Practices (restfulapi.net)
• 用名詞，不要用動詞
• 無論資源是單個或是一組，一律用眾數名詞
• 如果資源分成很多層級，頂層的資源原型(archetypes)就用單數名詞(因為「原型」是唯一的）
• 用連字符(Hyphen - )做分隔，不要用空隔符(Space)或底線(Underscore)
• 全小寫
• 不要用副檔名(File Extension)
• 用Query component (QueryString) 作為Filter

HTTP 回應 (Response)

Status Code

對於API回應中的HTTP Status Code必須要合適，例如什麼時候回應200，什麼時候回應201等等

See also:

• Best Practices for API Error Handling | Nordic APIs |