[ADP-701] 屬性設計

指導原則

• 屬性必須(MUST)使用駝峰式命名法(camelCase)，數字部分被視為小寫。

TIP

查看下方的設計考量。

• 屬性名稱必須(MUST)為ASCII字母數字字符、底線(_)或美元符號($)。
• 屬性不應(SHOULD NOT)使用特殊符號，如 : [ ] . ; %。
• 屬性名稱應(SHOULD)清晰、簡潔且具有自描述性。
• 屬性名稱應(SHOULD)使用完整單詞而非縮寫，除非該縮寫比完整單詞更常用。
  • 不應(SHOULD NOT)使用特定領域才知道的專用縮寫，見參考資料。
• bool 屬性應(SHOULD)使用"is"、"has"或"can"等前綴(例如，"isActive"、"hasPermission"、"canEdit")。
• 表示集合的屬性應使用複數名詞(例如，"users"、"items"、"orderLines")。

設計思考

JSON屬性有兩種常見的命名約定:

1. 駝峰式(camelCase)
2. 蛇形式(snake_case)

雖然有些公司/組織會使用蛇形式來匹配查詢參數約定(如underline_snakecase)，但這並不直觀。因此，我們選擇使用駝峰式命名JSON屬性，以保持一致性和可讀性。

TIP

💡 當屬性需要包含在URL中時，將駝峰式轉換為短橫線式(kebab-case)，以符合我們的路徑命名約定。

示例

基本屬性命名

{
  "userName": "johnDoe",
  "emailAddress": "john@example.com",
  "isActive": true,
  "hasSubscription": false,
  "orderItems": [
    {
      "productId": "12345",
      "quantity": 2
    }
  ]
}

查詢參數示例

GET /users?filter.userName=johnDoe&filter.emailAddress=john@example.com HTTP/1.1

URL路徑示例

GET /users HTTP/1.1

HTTP/1.1 200 OK

{
  users: [
    {
      registeredApplications: []
    }
  ]
}

假設我們在用戶模式中有 registeredApplications 屬性; 當我們需要在URI中應用該屬性時，需要將其轉換為 kebab-case。

GET /registered-applications HTTP/1.1

參考

設計參考：縮寫相關命名約定

• Google API 設計命名約定
• Swift API 設計指南
• Watson Developer Cloud API 指南
• ADIDAS API - JSON

Changelog

• 2024.11.04: Add field name limit