REST API 包括和排除子资源

Question

我正在尝试确定一种 RESTful 方式，以便针对特定请求随意包含和排除子资源。

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

获取部门/321

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

可能有一个很大的子部门列表。 GET departments资源也将包括每个部门和每个部门的子部门。大量数据。

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

获取部门/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"
       }
       ...
    ]
}

或排除过滤器:

GET部门/321？排除=子部门

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

尽管如果排除了子资源，我们可能需要包含指向子资源的链接？

GET部门/321？排除=子部门

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

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

Answer 1

我添加这些参数没有任何问题，所以继续使用它，最重要的部分是您管理 http 状态代码，响应具有读取数据的良好结构(并且您拥有它!)

另外，如果您想以另一种方式查看，请使用 OData:Web API and OData