記得第一次接觸到 API 設計的 task 時，就被同事 review 不正確的命名和不合邏輯的階層，因此想透過分享幾個自己曾經犯的錯誤來給大家!

當設計 API 時，遵循一些原則可以確保 API 既直觀又可擴展，並且易於維護。以下是一些整理出來設計 Restful API 的要點:

1. 使用名詞表示資源
REST 最關鍵的原則之一就是把 API 分配到不同的資源，並使用 HTTP 的方法(GET, POST, PUT, PATCH, DELETE)來操作，而資源設計命名時，使用名詞而非動詞。

• e.g. :
  • 良好：/users（使用者)、/record（紀錄）
  • 不佳：/getUsers（獲取使用者）、/createRecord（創建紀錄)

2. 使用有意義的名稱
選擇清晰且具有描述性的名稱，以表達資源的目的。

• e.g. :
  • 正常：/user（使用者)、/record（紀錄）
  • 不佳：/thing1、/thing2

3.使用連字符 (-) 改善 URI 的可讀性
為了讓 URL 更有可讀性，使用連字符（-）來提高長路徑段名稱的可讀性。
一開始我還不熟的時候用過( _ )，馬上被同事 review。

• e.g. :
  • http://test.blog/blogs/yusin/this-is-my-first-post

但如果要使用如 this_is_my_first_post 或 ThisIsMyFirstPost 也沒有說一定不行，只要整個專案都維持一致性即可。

4. 使用階層結構
設計時應把階層 (hierachy)的結構考量進來，
使用階層的結構來更明確的讓使用者知道更直覺的猜到資源的位置與內容。

• e.g. :
  • 用戶及其訂單：/users/{userId}/orders
  • 訂單及其項目：/records/{recordId}/items

更進一步的話，可以保持 API 程式的檔案結構和 API 路徑的一致性，這個做法可以讓開發人員更好的維護和快速的理解程式碼。

5. 正確使用 HTTP 方法
結合 URL 和 HTTP 方法來定義操作：

• GET /users：獲取使用者列表
• POST /users：創建新使用者
• GET /users/{userId}：獲取特定使用者
• PUT /users/{userId}：更新使用者(整體
• PATCH /users/{userId}：更新使用者(部分
• DELETE /users/{userId}：刪除使用者

6. 保持 URL 簡單扁平
避免多層的嵌套結構，讓 URL 複雜且難以管理。

• e.g. :
  • 正常：/users/{userId}/records
  • 不佳：/users/{userId}/records/{recordId}/items/{itemId}/details

7. 使用 HTTP 狀態碼
除了 URL 外，還應使用合適的 HTTP 狀態碼來指示 API 請求的結果：

• 2xx: 成功

• 4xx: 使用者操作問題

• 5xx: 伺服器錯誤

• e.g. :

  • 200 OK：成功的請求
  • 201 Created：成功創建資源
  • 204 No Content：表示伺服器已成功完成請求，但沒有額外的資訊需要返回。
  • 400 Bad Request：伺服器無法處理，可能是帶的參數錯誤
  • 404 Not Found：資源不存在
  • 500 Internal Server Error：伺服器錯誤

8. 具有可擴展性
設計 URL 時應考慮未來的擴展，避免破壞現有的客戶端功能。

• e.g. :

  //透過 v1/v2/v3 版本的控制，讓 API 有重大更新時，v1 的使用者能繼續使用。
  /api/v1/users/{user_id} 
  
  //這是單純顯示圖像是否被編輯過
  image.edit = {true, false}
  //如果使用 Enum 就能讓未來有更多延展性
  image.status = {add, edit, deleted}
  

9. 可相容性佳
在設計 API 時需要考慮到向下相容（downward compatibility），當未來 API 出現更新後，不應該讓使用者因為 API 更新而需要改變原本的操作。

10. 具有冪等性
API 需具有冪等性(idempotent)，指的是不管執行多少次請求，回傳的結果都應該要是相同的。
冪等性適用於 GET, PUT, DELETE 的方法中，每次獲取、整體更新、刪除相同的資源結果不應該會有所改變。

以上討論的幾點，是我整理比較常見的一些設計 API 需要注意的點，如果有其他認為也很重要的，也歡迎留言補充!

Reference:

• https://blog.restcase.com/7-rules-for-rest-api-uri-design/
• https://css-tricks.com/guidelines-for-uri-design/