RESTful API（表述性狀態轉移API）是一種用於網頁應用程式之間互動的網路介面設計風格。 REST 是一組架構原則和約束，而不是標準或協定。當 Web 服務是「RESTful」時，它遵循 REST 原則並提供高效、可靠且可擴展的網路服務。
在 RESTful 服務中，每個請求都應包含處理該請求所需的所有必要資訊。伺服器不應保留有關客戶端請求的任何狀態資訊。
RESTful 架構可能由多層組成，每層執行特定的功能。這種結構允許開發更複雜和更強大的應用程式。
URI 設計
在 RESTful API 設計中，URL（統一資源定位器）通常表示資源（物件），而 HTTP 方法（例如 GET、POST、PUT、DELETE 等）表示對這些資源的操作（動詞）。這種設計風格強調資源的狀態和表現而不是動作。
動詞 + 受詞
RESTful API 中的動詞通常是五種 HTTP 方法，對應 CRUD 操作：
-
取得：讀取
-
POST : 建立
-
PUT ：更新
-
PATCH ：更新（通常為部分更新）
-
刪除：刪除
根據 HTTP 規範，動詞應該永遠大寫。
受詞必須是名詞
在設計 API 時，URL（統一資源定位器）通常表示作為 HTTP 動詞的物件的資源。根據 RESTful 設計原則，URL 應該是名詞而不是動詞，因為它們代表的是「資源」集合或單一實例，而不是動作。
錯誤範例：
-
/getAllCars -
/createNewCar -
/deleteAllRedCars
這些 URL 包含動詞（例如 get、create、delete），它們描述的是操作而不是資源本身。這種設計不符合RESTful語意標準。
正確做法：
URL 應該專注於描述資源而不是操作。以下是合規 URL 設計的範例：
-
/users：代表使用者集合 -
/users/123：代表具有特定 ID（123）的單一用戶
在上面的例子中， /users和/users/123都是名詞，分別代表使用者集合和特定的使用者資源。這樣的URL設計使得API更容易理解，並且符合RESTful以資源為導向的原則。
透過遵循此命名約定，我們確保 API 路徑清晰、一致且易於理解和維護。
複數 URL
通常建議在 URL 中使用複數形式以保持一致性和清晰度，因為它們通常代表資源集合。
當您的 URL 指向資源集合時，請使用複數名詞。例如，使用/users而不是/user來表示所有使用者的集合。
即使指向單一資源，也建議使用複數形式。例如/users/123代表 ID 為 123 的使用者。
當資源具有層次關係時，URL 應該反映這種結構。例如， /users/123/posts可以表示使用者 123 的貼文集合。
避免深度嵌套的 URL
常見的情況是，當資源需要多層分類時，會導致 URL 嵌套很深，例如檢索特定作者的某一類別的文章：
GET /authors/12/categories/2這樣的 URL 很難擴展，語意不清楚，通常需要付出額外的努力才能理解。更好的方法是使用第一級以外的查詢參數：
GET /authors/12?categories=2另一個例子是查詢已發表的文章。您可以像這樣設計 URL：
GET /articles/published然而，使用查詢參數顯然是更好的方法：
GET /articles?published=true狀態程式碼
狀態程式碼必須準確
對於每個客戶端請求，伺服器必須使用 HTTP 狀態程式碼和資料進行回應。
HTTP 狀態碼是一個三位數字，分為五類：
-
1xx ：訊息
-
2xx ：成功
-
3xx ：重定向
-
4xx ：客戶端錯誤
-
5xx ：伺服器錯誤
這五個類別包含超過 100 個狀態程式碼，涵蓋了大多數可能的情況。每個狀態程式碼都有一個標準（或常規接受）的含義，客戶端只需檢查狀態程式碼就可以確定發生了什麼。因此，伺服器應該回傳盡可能最精確的狀態程式碼。
API 不需要1xx狀態碼。以下是其他四個類別的解釋。
2xx 狀態程式碼
不同的HTTP請求方法應該傳回對應的狀態碼來表示請求結果。雖然200 OK是一般的成功回應，但應根據方法使用更精確的狀態碼：
-
GET：200 OK–請求成功，返回資源。
-
POST：201 已建立– 已成功建立新資源，且回應通常包含資源的 URI。
-
PUT：200 OK 或 204 無內容– 用於完整資源更新。如果返回內容，則使用200 ；如果不是，請使用204 。
-
PATCH：200 OK 或 204 No Content – 用於部分更新，類似於 PUT。 204表示沒有返回內容。
-
DELETE：204 無內容– 表示資源已成功刪除，通常回應中沒有內容。
-
202 已接受– 請求已被接受但尚未處理，對於非同步操作很有用。
-
206 部分內容– 表示部分回應，通常用於客戶端使用Range標頭請求大檔案的一部分時。
3xx 狀態程式碼
API 通常不使用301（永久重定向）或302（暫時重定向，包括 307），因為它們主要與瀏覽器級導航相關。 API 可以在應用程式層級處理這種情況。
但是，API 可以使用303 See Other ，它引用另一個 URL。與302和307類似，它表示“暫時重定向”，但303專門用於POST、PUT 和 DELETE請求。與302不同，瀏覽器不會自動遵循303重定向，而是允許使用者決定下一步。
回應範例：
HTTP/1.1 303 See Other
Location: /api/orders/123454xx 狀態程式碼
4xx狀態程式碼表示客戶端錯誤。常見的有：
-
400 錯誤請求– 伺服器不理解客戶端的請求，不處理它。
-
401 未授權– 使用者未提供身份驗證憑證或身份驗證失敗。
-
403 禁止– 使用者身分驗證成功，但缺乏存取資源的權限。
-
404 未找到– 請求的資源不存在或不可用。
-
405 方法不允許– 使用者驗證成功，但使用了不允許的 HTTP 方法。
-
410 Gone–請求的資源已被永久刪除。
-
415 不支援的媒體類型– 不支援請求的格式。例如，如果 API 僅傳回 JSON，但用戶端請求 XML，則應傳回此狀態。
-
422 無法處理的實體– 客戶端提供了無法處理的附件，導致請求失敗。
-
429 請求過多– 用戶端已超出允許的請求數量。
5xx 狀態程式碼
5xx狀態碼表示伺服器錯誤。 API 通常不會向使用者公開內部伺服器詳細訊息，因此通常僅使用兩種狀態程式碼：
-
500 內部伺服器錯誤– 用戶端請求有效，但伺服器在處理時遇到意外問題。
-
503 服務不可用– 伺服器暫時無法處理請求，通常在維護期間使用。
伺服器回應
不返回純文字
API 回應不應是純文本，而應是結構化的 JSON 物件，以確保標準格式。伺服器的Content-Type標頭應設定為application/json 。
客戶端還應透過在其請求中設定Accept標頭來指定它接受 JSON 回應：
GET /orders/2 HTTP/1.1
Accept: application/json不要回傳 200 錯誤狀態程式碼
一種不正確的方法是即使發生錯誤也始終返回200 OK ，並在回應正文中包含錯誤詳細資訊。這迫使客戶端解析回應主體以確定請求是否失敗，從而破壞了狀態程式碼的目的。
不好的例子：
HTTP/1.1 200 OK
Content-Type: application/json
{
"status": "failure",
"data": {
"error": "Expected at least two items in list."
}
}在這種情況下，請求失敗，但是伺服器仍然回傳200 OK 。客戶端必須檢查回應主體中的"status": "failure"來偵測錯誤。這種方法不符合 RESTful 風格，並且使錯誤處理更加複雜且容易出錯。
正確範例：
狀態程式碼應該表明請求的結果。應使用適當的狀態程式碼來傳達錯誤，而回應主體則提供更多詳細資訊。
例如，如果請求無效，伺服器應該傳回400 Bad Request ，並以 JSON 格式傳回錯誤詳情：
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error": "Invalid payload.",
"detail": {
"surname": "This field is required."
}
}這裡， 400明確表示請求無效，而回應主體提供了具體的錯誤詳細訊息，以幫助客戶端了解問題。
提供連結
在 RESTful API 中，在回應中包含連結是一種常見的做法。這遵循超媒體作為應用程式狀態引擎 (HATEOAS)原則，增強了 API 的可發現性和自我描述性。
以下是包含連結的兩種常見方式：
使用 HAL（超文本應用程式語言）
HAL 是一種流行的超媒體格式，表示資源之間的關係。它使用 JSON 回應中的_links欄位：
{
"id": 1,
"name": "Example",
"_links": {
"self": {
"href": "http://api.example.com/resource/1"
},
"related": {
"href": "http://api.example.com/resource/2"
}
}
}直接在 JSON 中嵌入連結
{
"id": 1,
"name": "Example",
"links": {
"self": "http://api.example.com/resource/1",
"related": "http://api.example.com/resource/2"
}
}內容退貨政策
在 RESTful API 設計中， POST請求用於建立新資源。回應是否應包含新建立的資源取決於實施需求。有兩種常見的方法：
1. 返回建立的資源
此方法包括201 Created狀態程式碼和回應中新資源的完整詳細資訊。它還包括指向資源 URI 的Location標頭。
HTTP/1.1 201 Created
Location: /resources/123
Content-Type: application/json
{
"id": 123,
"name": "New Resource"
}2. 不返回內容
或者，伺服器可以選擇僅傳回帶有Location標頭的201 Created或204 No Content回應，而省略資源詳細資料。這可以最大限度地減少資料傳輸並讓客戶端決定是否稍後檢索資源。
HTTP/1.1 201 Created
Location: /resources/123結論
RESTful API遵循HTTP協議，強調資源表述和無狀態互動。 RESTful 架構透過使用標準 HTTP 方法（GET、POST、PUT、DELETE）和精確的狀態碼，提供了一種簡單、高效且易於維護的方式來建立網路應用程式。這種方法增強了 Web 服務的可擴充性、靈活性和可維護性。
我們是 Leapcell，您託管後端專案的首選。
Leapcell是用於 Web 託管、非同步任務和 Redis 的下一代無伺服器平台：
多語言支援
- 使用 Node.js、Python、Go 或 Rust 進行開發。
免費部署無限專案
- 僅按使用量付費 — 無請求，無費用。
無與倫比的成本效率
-
按需付費，無閒置費用。
-
例如：25 美元支援 694 萬個請求，平均回應時間為 60 毫秒。
簡化的開發人員體驗
-
直覺的使用者介面，輕鬆設定。
-
完全自動化的 CI/CD 管道和 GitOps 整合。
-
即時指標和日誌記錄可提供可操作的見解。
輕鬆實現可擴展性和高性能
-
自動擴展以輕鬆處理高並發。
-
零營運開銷－只需專注於建設。
在文件中探索更多！
在 X 上關注我們： @LeapcellHQ
原文出處：https://dev.to/leapcell/mastering-restful-api-design-a-practical-guide-408
1) --- 會變成分隔線（上一行必須是空白）
2) # 會變成一級標題
3) ## 會變成二級標題
4) ### 會變成三級標題
5) **粗體文字**會顯示粗體文字
6) ```當第一行與最後一行會顯示程式碼
7) 請搜尋 Markdown 語法，了解各種格式