有效地設計RESTful API對於創建可擴展、可維護且易於使用的系統至關重要。雖然存在某些標準，但許多標準並不是嚴格的規則，而是指導 API 設計的最佳實踐。一種廣泛使用的 API 架構模式是 MVC（模型-視圖-控制器），但它本身並不能解決 API 設計的更精細方面，例如命名和結構。在本文中，我們將逐步介紹建置 REST API 的基本準則。

1. 命名約定與資源導向的設計 API 通常是圍繞資源定義的，資源代表系統中的實體，例如「使用者」、「產品」或「訂單」。資源可以是單一項目或集合，API 應提供直覺且清晰的方式與這些資源互動。

關鍵原則：
面向資源：圍繞資源而不是操作設計 API。資源應該被視為名詞，而不是動詞。例如：

/users 用於存取使用者集合。
/users/{userId} 用於存取特定使用者。
一致性：API 應該直觀。如果使用者可以從 /users 取得資源列表，他們應該期望能夠透過新增識別碼來取得單一資源：/users/{userId}.

集合與單一資源：

資源集合以複數名詞表示：/users、/products。
單一資源透過附加此資源的唯一識別碼來表示：/users/{userId}、/products/{productId}.

1. HTTP 方法定義操作，而非 URI 正在執行的操作（無論是檢索資料、建立新條目或更新現有資料）不應嵌入 URI 中。相反，HTTP 方法決定操作。

常見的 HTTP 方法及其用例：
GET：從伺服器檢索資料。

範例：GET /products 傳回所有產品的清單。
範例： GET /users/{userId} 檢索具有指定 userId 的使用者。
POST：在伺服器上建立新資源。

範例：POST /users 建立一個新使用者。
PUT：以新資料取代現有資源（完全更新）。

範例：PUT /users/{userId} 將使用者的資料完全替換為新資料。
PATCH：部分更新現有資源（部分更新）。

範例：PATCH /users/{userId} 僅更新指定的屬性，例如電話號碼。
DELETE：刪除資源。

範例：DELETE /users/{userId} 刪除指定 userId 的使用者。

1. REST 中的無狀態性 REST API 應該是無狀態的，這意味著每個 API 呼叫都必須包含伺服器處理請求所需的所有資訊。這確保每個請求都是自給自足的並且不依賴先前的請求。

範例：當發出 GET 請求來獲取使用者詳細資訊時，該請求必須包含所需的授權令牌，即使先前的請求已經對使用者進行了身份驗證。這在分散式系統中至關重要，因為不同的請求可能會到達不同的伺服器。

1. 避免特定於伺服器的資料儲存 任何單一 API 請求都不應依賴在特定伺服器上儲存臨時資料。在分散式系統中，傳入請求可能會路由到任何伺服器，因此無論哪個伺服器處理請求，都應該實現相同的結果。這就是為什麼會話狀態不應儲存在單獨的伺服器上。

解決方案：對於會話管理，使用集中式或分散式儲存系統（如 Redis）或無狀態驗證機制（如 JWT（JSON Web Token））。

1. 資源與資料庫表 您的 API 設計不應在資料庫表和 API 端點之間具有一對一的對應。 API 應公開邏輯上有意義的資源，這些資源可以組合來自多個表或來源的資料。

例子：
GET /orders/{orderId} 可能會檢索訂單詳細信息，結合訂單、order_items 和客戶表中的信息。

1. 資料類型的靈活性 REST API 不受資料庫的資料類型或表格結構的限制。您可以以最適合您的 API 消費者的方式建立您的回應。雖然 JSON 是最常用的格式，但如果需要，您可以自由傳回 XML 或 CSV 等其他格式的資料。

範例：GET /reports/{reportId} 端點可能會根據請求中的查詢參數或標頭傳回各種格式（JSON、CSV、PDF）的報表。
API 結構範例
為了將所有這些原則聯繫在一起，這裡有一個遵循這些最佳實踐的 API 結構範例：

GET /products：檢索所有產品。
GET /products/{productId}：檢索特定產品的詳細資訊。
POST /products：建立新產品。
PUT /products/{productId}：將產品替換為productId。
PATCH /products/{productId}：部分更新產品。
DELETE /products/{productId}：刪除產品。
在這種結構中，資源被明確定義，HTTP 方法指定要採取的操作，確保 API 乾淨直覺。

**結論
**設計 RESTful API 不僅僅涉及建立路由和處理 HTTP 方法。透過專注於資源、利用 HTTP 方法進行操作並遵守無狀態性，您可以建立直覺、可維護和可擴展的 API。請記住，API 應該是靈活且獨立於特定的資料庫結構，以便隨著系統的發展提供更多的適應性。

遵循這些約定可確保您的 API 設計既高效又用戶友好，從而最終增強 API 開發人員和消費者的體驗。