{"_id":"5828a16c922c9d0f00eec3db","category":{"_id":"5435693035740020002a1c20","__v":5,"pages":["5435693035740020002a1c22","552917a3a15e530d00af3cac","55297cdfa15e530d00af3d51","558d812ebeb7c719007f62b0","568160e14047cf0d004121ba"],"project":"5435693035740020002a1c1c","version":"5435693035740020002a1c1f","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2014-10-08T16:41:20.738Z","from_sync":false,"order":0,"slug":"overview","title":"Overview"},"version":{"_id":"5435693035740020002a1c1f","__v":14,"project":"5435693035740020002a1c1c","createdAt":"2014-10-08T16:41:20.702Z","releaseDate":"2014-10-08T16:41:20.702Z","categories":["5435693035740020002a1c20","551c03c1ff892b3700d1c57a","551ca3927405910d00900a59","551cac6448564a2f0024d89e","551cb4d848564a2f0024d8a3","551cb52db7a32b3b00d1ef78","5526e2064a7ac121004c6073","5526e5147d4a4417009516b3","5526e9877d4a4417009516bb","5528362cd9e1db2d00cd924d","5580240ebe698419008f2ba2","5580a7dabe698419008f2db6","568161799de23c0d00c54750","5866c905a2cbb31900f6f1aa"],"is_deprecated":false,"is_hidden":false,"is_beta":true,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1.0"},"__v":0,"project":"5435693035740020002a1c1c","user":"543568c135740020002a1c10","parentDoc":null,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-11-13T17:22:52.506Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":5,"body":"Many endpoints support the inclusion of child entities (sub-resources) within a resource.\n\nFor 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.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Basic Example\"\n}\n[/block]\nThe 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.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"GET /spaces/50?include=location\\n\\n{\\n    \\\"id\\\": 50,\\n    \\\"location_id\\\": 10,\\n    \\\"name\\\": \\\"Conference Room\\\",\\n    ...\\n    \\\"location\\\": {\\n      \\\"id\\\": 10,\\n      \\\"account_id\\\": 34,\\n      \\\"name\\\": \\\"HQ\\\",\\n      ...\\n    }\\n}\",\n      \"language\": \"http\",\n      \"name\": null\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Sub-sub-resources\"\n}\n[/block]\nIn 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:\n\n`include=space.location` on an entity would return it's parent space's location.","excerpt":"","slug":"including-sub-resources","type":"basic","title":"Including Sub-Resources"}

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. [block:api-header] { "type": "basic", "title": "Basic Example" } [/block] 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. [block:code] { "codes": [ { "code": "GET /spaces/50?include=location\n\n{\n \"id\": 50,\n \"location_id\": 10,\n \"name\": \"Conference Room\",\n ...\n \"location\": {\n \"id\": 10,\n \"account_id\": 34,\n \"name\": \"HQ\",\n ...\n }\n}", "language": "http", "name": null } ] } [/block] [block:api-header] { "type": "basic", "title": "Sub-sub-resources" } [/block] 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.