REST API including and excluding of subresources

Question

I am trying to determine a RESTful way to have subresources included and excluded at will for specific requests.

For example sake, this could be the original request:

GET departments/321

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

There could be a big list of sub departments. The GET departments resource would also then include every department AND each of those departments' subdepartments. A lot of data.

This could be solved by creating two separate resources:

GET departments/321

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

GET departments/321/subdepartments

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

But there may be occasions where the client software would prefer not to make multiple requests (for performance sake most likely). Perhaps by providing an include filter:

GET departments/321?include=subdepartments

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

Or an exclude filter:

GET departments/321?exclude=subdepartments

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

Although perhaps we need to include a link to the subresource if its excluded?

GET departments/321?exclude=subdepartments

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

Is there an acceptable RESTful way of performing the above including or excluding of subresources?

Answer 1

The proper REST services must use hypermedia (links) to connect to related resources. If we use a custom media type instead of something like JSON Collection or AtomPub, the response for the first call would look something like

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

You can call that link to get a resource with links to all subdepartments.

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

It works almost like browsing a web-site and clicking the links.

Read this blog post by Roy Fielding himself: http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven

There are obvious complexity and performance issues that could happen in this approach. Truely RESTful services make sense when the server app can evolve separately from the client. Otherwise, just use the approach with query string parameters.

Answer 2

I dont have any problem to add those parameters, so go ahead and use it, the most important part is that you manage the http status code, an the response have a good structure to read the data (and you have it!)

Also, if you want see another way, tru with OData: Web API and OData