為什麼編寫乾淨的 REST-API 設計很重要
在當今互聯的世界中，精心設計的 REST API 是高效且可擴展的應用程式的支柱。
編寫乾淨的 REST API 設計至關重要，原因如下：
增強的可用性：精心設計的 API 直覺且易於使用，適合各種技能水平的開發人員使用。這簡化了整合並縮短了學習曲線。
提高可維護性：乾淨的程式碼可以更輕鬆地辨識和修復錯誤、加入功能和擴展 API，從而提高可維護性。這確保了長期穩定性並降低了開發成本。
提高安全性：結構良好的 API 具有適當的身份驗證和授權機制，有助於防止未經授權的存取、資料外洩和其他安全漏洞。
增強的效能：簡潔的設計透過使用高效的資料結構、避免不必要的呼叫並最大限度地減少延遲來優化效能。這提供了無縫的用戶體驗並提高了整體應用程式效能。
縮短開發時間：明確定義的 API 規格和清晰的文件可消除猜測並減少大量測試的需要，從而加快開發速度。這節省了寶貴的開發時間和資源。
改進的可擴展性：簡潔的設計透過提供模組化架構來實現輕鬆的可擴展性，該架構可以輕鬆擴展以處理增加的流量或新功能。這確保了 API 可以隨著應用程式的需求而成長。
提高可重複使用性：設計良好的 API 可以在多個應用程式中重複使用，從而減少重複並提高一致性。這簡化了開發並節省了時間和精力。
改進的文件：簡潔的設計更容易記錄，讓開發人員清楚 API 的工作原理以及如何有效地使用它。這可以減少混亂並提高採用率。
URI規則
一個url的結構如下
scheme :// authority / path [?query][#fragment]
例如
https://soccer.api.org/teams/dortmund/players?name=Rona#2
有兩種類型的資源
集合資源：包含資源的集合。它可以比喻為資料庫關係
單例資源：包含單一資源。它可以比喻為資料庫記錄。
設計 Rest-Api 時
1 集合資源應該是複數
+ soccer.api.org/teams/dortmond
- soccer.api.org/team/dortmond
2 Singleton資源應該是單一的，可以用api後面資料庫系統中代表資源的唯一id來代替
+soccer.api.org/teams/dortmond/players/58c1aaae-205a-11ef-aeea-a64c74618950
3 URI 中沒有尾隨正斜杠
+soccer.api.org/teams/dortmond/players
-soccer.api.org/teams/dortmond/players/
4 使用連字號取代底線以提高 API 的可讀性
+ api.blog.com/blogs/this-is-my-blog
- api.blog.com/blogs/this_is_my_blog
5 URI 路徑中小寫字母優先於大寫字母
+ api.example.com/my-api/my-resource
- api.example.com/My-Api/My-Resource
6 URI 中沒有檔案副檔名
+ api.example.com/api/resource
- api.example.com/api/resource.json
7 CRUD 函數名稱不應在 URI 中使用
+ DELETE api.example.com/api/resource
- GET api.example.com/api.resource/delete
8 URI 的查詢元件只能在集合資源中使用
+ GET /users?role=admin
9 URI 的查詢元件應用於對集合結果分頁
+ GET /users?pageSize=25&pageStartIndex=50
HTTP 方法規則
| HTTP 方法 | 用途 |
|---|---|
| POST | 建立新資源。類似於建立 |
| GET | 獲取資源的表示。類似閱讀 |
| PUT | 透過替換整個資源來更新資源 |
| DELETE | 刪除資源 |
| PATCH | 透過更改所需資源的一部分來更新資源，而不取代整個資源。 |
| HEAD | 僅獲取響應頭而不是響應體 |
| OPTION | 獲取特定資源的所有可用選項 |
PUT 可用於建立和更新資源。但是，根據最佳實踐，通常建議使用 POST 來建立新資源，並使用 PUT 來完全取代現有資源。
版本控制
對 api 進行版本控制對於以下方面可能很重要：
保持向後相容性：版本控制可讓您引入新功能，而不會破壞依賴舊 API 版本的現有整合。使用者可以繼續使用熟悉的端點，而尋求新功能的使用者可以採用版本化的 API。
確保一致且設計良好的 API：跨版本的一致命名約定有助於提供使用者友善的體驗。更改端點會破壞這種體驗，而版本控制有助於避免這種情況。
結論
現在您已經掌握了這些 REST API 設計規則，是時候將它們付諸實現了！在下面的評論中分享您的 API 創作，讓我們一起建立一個設計良好且對開發人員友好的 API 世界。
原文出處：https://dev.to/ezekiel_77/rest-api-design-rules-2c4j
1) --- 會變成分隔線（上一行必須是空白）
2) # 會變成一級標題
3) ## 會變成二級標題
4) ### 會變成三級標題
5) **粗體文字**會顯示粗體文字
6) ```當第一行與最後一行會顯示程式碼
7) 請搜尋 Markdown 語法，了解各種格式