REST API包括和不包括子资源

Question

我正在尝试确定一种RESTful方式,以便为特定请求包含和排除子资源.

例如,这可能是原始请求:

GET部门/ 321

200 (Ok)
{
    "id": "321",
    "name": "Sales",
    "building": "The Foundary"
    "subdepartments": [
       {
          "id": "123",
          "name": "Training"
       },
       {
          "id": "224",
          "name": "Book Sales"
       }
       ...
    ]
}

可能有一个很大的子部门列表.GET departments然后,该资源还将包括每个部门和每个部门的子部门.很多数据.

这可以通过创建两个单独的资源来解决:

GET部门/ 321

200 (Ok)
{
    "id": "3",
    "name": "Sales",
    "building": "The Foundary"
}

GET部门/ 321 /分部门

200 (Ok)
[
   {
      "id": "123",
      "name": "Training"
   },
   {
      "id": "224",
      "name": "Book Sales"
   }
   ...
]

但有时客户端软件可能不愿意提出多个请求(出于性能原因).也许通过提供include过滤器:

GET部门/ 321？包括=子部门

200 (Ok)
{
    "id": "321",
    "name": "Sales",
    "building": "The Foundary"
    "subdepartments": [
       {
          "id": "123",
          "name": "Training"
       },
       {
          "id": "224",
          "name": "Book Sales"
       }
       ...
    ]
}

或排除过滤器:

获取部门/ 321？排除=子部门

200 (Ok)
{
    "id": "321",
    "name": "Sales",
    "building": "The Foundary"
}

虽然如果将其排除在外,我们可能还需要包含子资源的链接？

获取部门/ 321？排除=子部门

200 (Ok)
{
    "id": "321",
    "name": "Sales",
    "building": "The Foundary"
    "subdepartments": {
        "href" : "api.com/departments/321/subresources"
    }
}

是否有可接受的RESTful方式来执行上述操作,包括或排除子资源？

Answer 1

正确的 REST 服务必须使用超媒体（链接）来连接到相关资源。如果我们使用自定义媒体类型而不是 JSON Collection 或 AtomPub 之类的内容，则第一次调用的响应将类似于

{
    "id": "321",
    "name": "Sales",
    "building": "The Foundary"
    "links": [
          { "rel": "subdepartments", "href": "departments/321/subdepartments", "method": "get" }
     ]
}

您可以调用该链接来获取包含所有子部门链接的资源。

{
    ...
    "links": [
      { "rel": "subdepartment", "href": "departments/321/subdepartments/1", "method": "get" },
      { "rel": "subdepartment", "href": "departments/321/subdepartments/2", "method": "get" }
    ]
}

它的工作原理几乎就像浏览网站并单击链接一样。

阅读 Roy Fielding 本人撰写的博文： http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven

这种方法可能会出现明显的复杂性和性能问题。当服务器应用程序可以与客户端分开发展时，真正的 RESTful 服务才有意义。否则，只需使用带有查询字符串参数的方法。