Including related entities

To reduce the number of HTTP requests, some endpoints support including related entities in the response. Let's take GET pages/:id.json for example, which has a space relationship;

Note: the query parameter value matches the relationship property type (spaces).

As you can see, there's now another root property called included. This contains a property for each entity type included, spaces in this case. These properties are always maps with the id being the key, the value will contain full entity models (resource objects), i.e. space models in this case. This is the full spaces model with all of its properties including its resource identifier objects.

It's possible to include multiple relationships in one request; e.g. include=spaces,users. It's possible to include indirect relationships; e.g. include=spaces.users,spaces. This will include the space the page is linked to, as well as the user information for the space ie who created it, last updated etc.

All endpoints with resource identifiers objects support the included feature.

Feedback

If you have any feedback or suggestions, feel free to contact us at api@teamwork.com.

Request: GET .../pages/1.json

{
	"page": {
		...
		"space": { "id": 42, "type", "spaces" },
		...
	}
}

Request: GET pages/1.json?include=spaces

{
	"page": {
		...
		"space": { "id": 42, "type", "spaces" },
		...
	},
	"included": {
		"spaces": {
			"42" :{
                ...
            }
		}
	}
}