api - REST 风格的 API : Modelling a collection of resources that have access to another resource

Question

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

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

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

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

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

另一方面，我无法 POST 到 documents/{document-id}/users，因为我的目标不是创建新资源 - 我特别 不要't 想要创建一个。

我做错了吗？

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" }
                  ]
      }
    ]
  }
}