Including related entities

To reduce the number of HTTP requests, some endpoints support including related entities in the response. Let’s take GET deals/:id.json for example, which has an owner relationship;

Request: GET deals/1.json

Response:

{
	"deal": {
		...
		"owner": { "id": 17, "type", "users" },
		...
	}
}

If you were to request GET deals/1.json?include=owner, you would get the following:

{
	"deal": {
		...
		"owner": { "id": 17, "type", "users" },
		...
	},
	"included": {
		"users": [{
			"id": 17,
			...	
		}]
	}
}

Note: the query parameter value matches the relationship property name (owner).

As you can see, there’s now another root property called included. This contains a property for each entity type included, users in this case. These properties are always arrays contain full entity models (resource objects), i.e. user models in this case. This is the full user model with all of its properties including its resource identifier objects.

It’s possible to include to-many relationships; e.g. include=contacts. It’s possible to include multiple relationships in one request; e.g. include=contacts,owner. It’s possible to include indirect relationships; e.g. include=contacts.company,owner. This will include the deal’s contacts and those contacts’ companies, as well as the deals owner.

Note: you can’t change what’s returned in included directly. So if you want more contacts for example, increase the pageSize for the contacts relationships. See Pagination for more.

Not all relationships can be included. This is decided on an endpoint per endpoint basis. Each endpoint’s documentation will specify which includes are supported.

Feedback

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