rest - 设计 REST API : sub-collection and HTTP PATCH

Question

第一种情况:

假设我在我的 REST API 中有一个客户资源，可通过 /customers 和 /customers/{id} 端点访问。

鉴于一个客户可以有多个地址，我基本上有三种选择:

1. 添加一个 /customers/{id}/addresses 子集合端点。在这种情况下，我们可以GET/POST/PUT/DELETE到该端点以获取/添加/修改/删除一个地址。

2. 添加代表顶级地址集合的 /addresses 端点。

3. 不要创建另一个端点，地址在 GET /customers/{id} 请求中返回，并且可以使用 添加/修改/删除>PATCH 请求，例如。如果我们使用 JSON-PATCH :

   PATCH /customers/{id}
   
   {
       "op": "add",
       "path": "/addresses/-",
       "value": /* new address */
   }
   

对于“通用”API(即具有多个具有不同需求的不同客户端的公共(public) API)，哪个更合适？

第二种情况:

现在让我们考虑一个文档资源，它代表多个用户共享的文档，例如 Google 文档。每次用户开始编辑文档时，其 ID 都会添加到当前正在编辑该文档的用户列表中，例如:

GET /documents/{id}

{
    "data": /* ... */,
    "editors": ["userId1", "userId2"]
}

您会像上一个案例一样处理这个问题吗？

选项 #1 对我来说似乎不太自然，因为在这种情况下，编辑器只是一个 ID(在内部，一个外键)，我们可以考虑一个 ID(更常见的是简单的原始类型，例如字符串，整数等)作为资源？此外，为每个“子资源”创建不同的端点最终将有很多端点，而 PATCH 选项(#​​3)允许保留少量端点，同时提供额外的能力同时更新多个子资源，例如:

PATCH /documents/{id}

[
    {"op": "add", "path": "/editors/-", "value": "idUser"},
    {"op": "replace", "path": "/title", "value "new title"}
]

Answer 1

第一个选项。如果addresses属于客户，也就是说，不在不同客户之间共享(至少，在一般情况下)，我认为第一个选项非常适合 REST 方法，因为您将系统建模为资源的集合和它们之间的层次关系.

你也可以使用 PATCH结合第一个选项，以防您需要对地址进行部分更新(例如，如果您只需要修改街道名称)