RESTful API：对可以访问另一个资源的资源集合进行建模

Question

我正在构建一个 RESTful API，它将我的应用程序的用户公开为users。

我的应用程序还具有“文档”功能，每个用户都可以访问特定文档。我正在考虑通过users/{user-id}/documents 公开可访问文档来表示这一点的自然方式。

但是，从可用性的角度来看，我的客户必须能够获取（和修改）有权访问特定文档的用户。因此，我正在考虑将此表示“反转”为documents/{document-id}/users。

这些（尤其是后者）似乎是建立这种关系的正确方法吗？如果我确实采用了这样的解决方案，我该如何模拟“授予对文档的访问权限”？

我倾向于将一个预先存在的用户（大概是通过 GETing users 获得）放入 documents/{document-id}/users/{user-id}。然而，这似乎并不令人满意，因为我将执行“更新”操作，而不是实际更新资源，而是将其插入集合中。这在语义方面尤其成问题，因为我希望我的服务器端最终不考虑完整的、已发送的用户表示，而只是将 id 与预先存在的用户的 id 交叉引用为了创建一个关联。

另一方面，我不能 POST 到 documents/{document-id}/users，因为我的目标不是创建新资源 - 我特别不希望创建一个。

我做错了吗？

Answer 1

用户并不真正属于文档资源，对吧？您真正要说的是这些用户可以访问此文档。所以可能应该从 /documents/{document-id}/users 返回的不是用户实体的直接表示，而是用户对该实体的权限的某种表示。也许该表示的内部是指向完整用户本身的链接。

所以，如果您要返回 Collection+JSON 媒体类型，也许您会有类似的内容：

{
  "collection":
  {
    "version":"1.0",
    "href":"/documents/document123",
    "items":
    [
      {
         "href":"/documents/document123/users/user3841",
         "data": [ 
                    { "name":"userName", "value":"John Doe", "prompt":"User Name" },
                    { "name":"permissions", "value":["Read"], "prompt":"User Permissions" }
                 ],         
         "links": [ 
                    { "rel":"user", "href":"/users/3841" }
                  ]
      },
      {
         "href":"http//whatever/documents/document123/users/user9387",
         "data": [ 
                    { "name":"userName", "value":"John Doe", "prompt":"User Name" },
                    { "name":"permissions", "value":["Read"], "prompt":"User Permissions" }
                 ],         
         "links": [ 
                    { "rel":"user", "href":"/users/9387" }
                  ]
      }
    ]
  }
}