[ADP-310] 集合語義
INFO
本 ADP 提供了 RESTful API 集合語義的概述。
指南
- 集合應該(SHOULD)在 URI 中使用複數名詞表示。
- 集合資源應(SHOULD)支持分頁、過濾和排序。
- 集合回應應(SHOULD)包含有關集合的元數據(例如總計數、分頁連結)。
- 集合中的個別資源表示應(SHOULD)與其獨立表示一致。
集合操作
檢索集合
- 使用 GET 檢索資源集合。
- 支持用於分頁、過濾和排序的查詢參數。
示例:
http
GET /users?page=2&per_page=100&sort=name HTTP/1.1在集合中創建資源
- 使用 POST 在集合中創建新資源。
- 返回創建的資源表示和 201 Created 狀態碼。
示例:
http
POST /users HTTP/1.1
Content-Type: application/json
{
"name": "John Doe",
"email": "john@example.com"
}批量操作
- 考慮支持集合的批量創建、更新或刪除操作。
- 對批量操作請求和回應使用一致的格式。
批量創建示例:
http
POST /users/bulk HTTP/1.1
Content-Type: application/json
{
"users": [
{ "name": "User 1", "email": "user1@example.com" },
{ "name": "User 2", "email": "user2@example.com" }
]
}