Including Sub-Resources

Many endpoints support the inclusion of child entities (sub-resources) within a resource.

For example, with a Space entities, the space's Location is includable as a sub-resource. This allows the client to compose API calls more responsibly to avoid making N API calls by eager-loading the necessary data onto a single call.

Basic Example

The following example shows how to eager-load the location entity onto a Space result. This allows you to get the space and it's location in a single request.

GET /spaces/50?include=location

{
    "id": 50,
    "location_id": 10,
    "name": "Conference Room",
    ...
    "location": {
      "id": 10,
      "account_id": 34,
      "name": "HQ",
      ...
    }
}

Sub-sub-resources

In rare scenarios, sub-resources of sub-resources are allowed to be included as well. In this case, a dot (.) syntax is used to denote the ancestry. For example:

include=space.location on an entity would return it's parent space's location.