ADP
API Design PrincipleBETA

繁體中文

English

繁體中文

English

Appearance

[ADP-309] URI 格式約定 ​

reviewing phase 1

與ADP-306有重複

指導原則 ​

  • 必須(MUST)使用 kebab-case 命名 URI 中的資源名稱和修飾詞。
  • 應該(SHOULD)在 URI 的所有部分使用小寫字母。
  • 必須(MUST)使用連字符 (-) 分隔多詞資源名稱或修飾詞中的單詞。
  • 應該(SHOULD)盡可能保持 URI 簡短且具描述性。
  • 不得(MUST NOT)在 URI 中包含檔案副檔名 (如 .json、.xml)。
  • 應該(SHOULD)為集合資源使用複數名詞。
  • 可以(MAY)為單例資源或特定實例使用單數名詞。
  • 應該(SHOULD)使用名詞而非動詞來表示資源。

設計思路 ​

此規則涉及資源集合的命名以及用於描述集合的修飾詞/裝飾器。一致的 URI 格式可以提高 API 的可讀性、可預測性和整體開發者體驗。

TIP

💡 當需要將路徑放入屬性時，你需要將其轉換為 camelCase，因為我們定義 JSON 中的屬性應該使用 camelCase。

範例 ​

好的範例:

http
https://api.example.com/api-principles
https://api.example.com/api-principles/recently-visited
https://api.example.com/users
https://api.example.com/users/123/profile-pictures

不好的範例:

http
https://api.example.com/APIprinciples
https://api.example.com/api_principles/recentlyVisited
https://api.example.com/user
https://api.example.com/users/123/profilePictures.jpg

實施細節 ​

  1. 資源命名:

    • 為集合使用複數名詞: /users, /products, /orders
    • 為單例或特定實例使用單數名詞: /user/profile, /product/featured

  2. 查詢參數:

    • 使用 camelCase 命名查詢參數: /users?sortBy=lastName&filterBy=active

  3. 版本控制:

    • 如果需要 API 版本控制，將其包含在路徑開頭: /v1/users, /v2/products

  4. 嵌套資源:

    • 使用邏輯嵌套表示關係: /users/123/orders/456

  5. 操作:

    • 對於不符合標準 CRUD 操作的操作，使用表示操作結果的名詞: /users/123/password-reset 而不是 /users/123/reset-password

    關於重置密碼的 API 設計

    在設計與授權、驗證相關的 API 時，總是存在一些爭議，認為這些 API 不太符合 "RESTful" 的精神。這方面的爭議在網路上不少，有些人主張應該將登入行為抽象化為 session，然後將 session 作為資源進行設計；另一些人則認為登入相關操作應該以 RPC 風格進行設計。

    本規範認為，隨著 OAuth2.0 和 OIDC，已經有了成熟的解決方案。因此，可以直接參考實現了 OAuth2.0/OIDC 的身份提供者（IDP）是如何設計的，以重置密碼為例，以下幾種方法較符合本規範的思想：

    http
    DELETE /..../password

(https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/resources_sobject_user_password_delete.htm)

POST /.../password-reset

(https://auth0.com/docs/authenticate/database-connections/password-change)

PATCH /.../user with { password }

(https://auth0.com/docs/authenticate/database-connections/password-change#directly-set-the-new-password)

    這些方法可以作為設計驗證授權相關 API 的參考。

相關 ADP ​

參考資料 ​

Changelog ​

  • 2024.09.24 Add password-reset api design thinking