[ADP-314] 資源標識符
指導方針
必須(MUST)為資源設置標識符欄位。
應該(SHOULD)優先選擇字串類型而非數字作為標識符。
可以(MAY)使用 UUID 或 ULID 生成
id。TIP
💡 作為父資源一部分且無法獨立存在的子資源可能沒有
id欄位。相反，它們仍會有一個唯一的欄位，如type或name。不應(SHOULD NOT)使用遞增整數作為 id 生成邏輯。
TIP
💡 使用遞增整數可能導致潛在的安全風險，例如 ID 容易被預測，這可能被利用來訪問未經授權的資源。此外，遞增整數在分佈式系統中可能會導致可擴展性和唯一性問題。
TIP
💡 然而，如果資源數量保證很小，使用 UUID 可能過於複雜。如果沒有安全顧慮，API 設計者可以選擇使用遞增數字(轉換為字串)。
不應(SHOULD)使用外部 ID 作為資源 ID。所謂的外部 ID 指的是不受你控制的 ID，比如第三方系統產生的 ID。
必須(MUST)使用 URL 友好的標識符
- 為了簡化資源 ID 在 URL 中的編碼，它們必須符合正則表達式
[a-zA-Z0-9:._\-/]*。資源 ID 應只包含使用字母、數字、下劃線、減號、冒號、句點，以及 - 在極少數情況下 - 斜線的 ASCII 字串。
- 為了簡化資源 ID 在 URL 中的編碼，它們必須符合正則表達式
應該(SHOULD)在適當的情況下考慮使用有意義的標識符，在可讀性和安全性之間取得平衡。
必須(MUST)確保標識符在資源類型的範圍內是唯一的。
應該(SHOULD)在相關資源之間使用一致的標識符格式。
示例
主要資源 JSON 表示
json
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"name": "主要資源",
"type": "primary",
"subResource": {
"type": "example",
"name": "子資源"
}
}URI 引用
- 主要資源:
http
GET /resources/123e4567-e89b-12d3-a456-426614174000 HTTP/1.1- 主要資源中的子資源:
http
GET /resources/123e4567-e89b-12d3-a456-426614174000/sub-resource HTTP/1.1最佳實踐
- 一致性:在整個 API 中保持一致的標識符格式。
- 不可變性:一旦分配，資源標識符不應更改。
- 不透明性:避免在標識符中編碼敏感資訊。
- 性能:考慮標識符選擇對數據庫索引和查詢性能的影響。
- 可擴展性:選擇能夠適應未來增長的標識符格式。