{"_id":"56afdda49d32e30d0006d3c8","category":{"_id":"56acd8f95ac4060d0027865e","__v":7,"project":"56acd71213ac890d001c3c7a","version":"56acd71213ac890d001c3c7d","pages":["56ad4897c00d120d00744350","56afce739d32e30d0006d3b5","56afd4573a5b810d00745d77","56afd5049d32e30d0006d3bf","56afdc7d9d32e30d0006d3c5","56afdda49d32e30d0006d3c8","56b136c636d2580d002478d2"],"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2016-01-30T15:38:33.013Z","from_sync":false,"order":2,"slug":"restful-api","title":"REST API"},"project":"56acd71213ac890d001c3c7a","githubsync":"","parentDoc":null,"user":"56acd6caa040860d00ac94a2","__v":12,"version":{"_id":"56acd71213ac890d001c3c7d","project":"56acd71213ac890d001c3c7a","__v":15,"createdAt":"2016-01-30T15:30:26.928Z","releaseDate":"2016-01-30T15:30:26.928Z","categories":["56acd71313ac890d001c3c7e","56acd8f113ac890d001c3c81","56acd8f95ac4060d0027865e","56acd93a13ac890d001c3c82","56ad20660ab3c00d00ce3347","56ad356a2a7860170013f714","56ad47eb0ab3c00d00ce334f","56afd523bc304a0d00ace1df","56b29a019621f20d00efb37e","56b657e11bc6970d009feee7","5845cc3c39950c1b002afe77","5845cde163c11b250037967e","5846efd45d064323007b17b4","588604da4674e32300efd160","588627882393d50f00f1322c"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1.0"},"updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-02-01T22:35:16.550Z","link_external":false,"link_url":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":2,"body":"Some of the REST API endpoints allow you to pass in additional information in an ```include``` parameter. This parameter is used to request additional data that may be nested within a JSON response. \n\n**For example, here's the /channel/subscribers endpoint JSON with no ```include``` parameter:** \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"var params = {\\n  access_token: \\\"CHANNEL_ACCESS_TOKEN\\\",\\n  limit: 1,\\n};\\n\\n$.getJSON('https://gamewisp.com/api/pub/v1/channel/subscribers/', params, function(json) {\\n    console.log(json);\\n});\",\n      \"language\": \"javascript\"\n    },\n    {\n      \"code\": \"<?php\\n\\n$client = new GuzzleHttp\\\\Client();\\n\\ntry {\\n\\n  $response = $client->get('https://gamewisp.com/api/pub/v1/channel/subscribers', [\\n    'query' => [\\n      'access_token'  => 'CHANNEL_ACCESS_TOKEN',\\n      'limit': 1,\\n    ]\\n  ]);\\n\\n  $result = $response->json();\\n\\n} catch (Exception $e) {\\n\\n  //error\\n  $result = $e->getResponse()->json();\\n\\n}\",\n      \"language\": \"php\"\n    },\n    {\n      \"code\": \"https://gamewisp.com/api/pub/v1/channel/information?access_token=CHANNEL_ACCESS_TOKEN&limit=1\",\n      \"language\": \"text\",\n      \"name\": \"Sample URL\"\n    }\n  ]\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"result\\\": {\\n    \\\"status\\\": 1,\\n    \\\"message\\\": \\\"Subscribers Retrieved\\\"\\n  },\\n  \\\"data\\\": [\\n    {\\n      \\\"id\\\": 26,\\n      \\\"user_id\\\": 87545,\\n      \\\"status\\\": \\\"active\\\",\\n      \\\"subscribed_at\\\": null,\\n      \\\"tier_id\\\": \\\"3\\\",\\n    }\\n  ],\\n  \\\"meta\\\": {\\n    //...meta information, cursor, etc.\\n   }\\n  }\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\nThe above ```data``` object includes the ```user_id``` property which defines the user id of the subscriber. This is an acceptable return, but annoying if you have to hit a separate endpoint just to get the user information for this subscriber.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Working with the include Parameter\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Accepted Includes Vary by Endpoint\",\n  \"body\": \"If an endpoint accepts an ```include``` parameter, it will be indicated on that particular endpoint's documentation page.\"\n}\n[/block]\n**Instead of making mutiple API calls to difference resources, you can use the ```include``` parameter to immediately get a nested resource. Like so:** \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"var params = {\\n  access_token: \\\"CHANNEL_ACCESS_TOKEN\\\",\\n  include: \\\"user\\\"\\n  limit: 1,\\n};\\n\\n$.getJSON('https://gamewisp.com/api/pub/v1/channel/subscribers/', params, function(json) {\\n    console.log(json);\\n});\",\n      \"language\": \"javascript\"\n    },\n    {\n      \"code\": \"<?php\\n\\n$client = new GuzzleHttp\\\\Client();\\n\\ntry {\\n\\n  $response = $client->get('https://gamewisp.com/api/pub/v1/channel/subscribers', [\\n    'query' => [\\n      'access_token'  => 'CHANNEL_ACCESS_TOKEN',\\n      'limit'=> 1,\\n      'include' => 'user'\\n    ]\\n  ]);\\n\\n  $result = $response->json();\\n\\n} catch (Exception $e) {\\n\\n  //error\\n  $result = $e->getResponse()->json();\\n\\n}\",\n      \"language\": \"php\"\n    },\n    {\n      \"code\": \"https://gamewisp.com/api/pub/v1/channel/information?access_token=CHANNEL_ACCESS_TOKEN&include=user&limit=1\",\n      \"language\": \"text\",\n      \"name\": \"Sample URL\"\n    }\n  ]\n}\n[/block]\nAnd receive the user object for each subscriber returned in the response:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"result\\\": {\\n    \\\"status\\\": 1,\\n    \\\"message\\\": \\\"Subscribers Retrieved\\\"\\n  },\\n  \\\"data\\\": [\\n    {\\n      \\\"id\\\": 26,\\n      \\\"user_id\\\": 87545,\\n      \\\"status\\\": \\\"active\\\",\\n      \\\"subscribed_at\\\": null,\\n      \\\"tier_id\\\": \\\"3\\\",\\n      \\\"user\\\": {\\n        \\\"data\\\": {\\n          \\\"id\\\": 87545,\\n          \\\"username\\\": \\\"test\\\",\\n          \\\"banned\\\": false,\\n          \\\"deactivated\\\": false,\\n          \\\"created_at\\\": \\\"2015-11-10 00:00:00\\\",\\n          \\\"links\\\": {\\n            \\\"uri\\\": \\\"/user/87545\\\"\\n          }\\n        }\\n      }\\n    }\\n  ],\\n  \\\"meta\\\": {\\n    //meta information ...cursor, etc.\\n    }\\n  }\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Advanced include Parameter Usage\"\n}\n[/block]\nIt's possible to use multiple includes when available. For example, the /channel/subscribers endpoint can accept **user**, **tier**, or even a combination of both separated by a comma (e.g., **'user,tier'**) as a valid include parameter.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"var params = {\\n  access_token: \\\"CHANNEL_ACCESS_TOKEN\\\",\\n  include: \\\"user, tier\\\"\\n  limit: 1,\\n};\\n\\n$.getJSON('https://gamewisp.com/api/pub/v1/channel/subscribers/', params, function(json) {\\n    console.log(json);\\n});\",\n      \"language\": \"javascript\"\n    },\n    {\n      \"code\": \"<?php\\n\\n$client = new GuzzleHttp\\\\Client();\\n\\ntry {\\n\\n  $response = $client->get('https://gamewisp.com/api/pub/v1/channel/subscribers', [\\n    'query' => [\\n      'access_token'  => 'CHANNEL_ACCESS_TOKEN',\\n      'limit'=> 1,\\n      'include' => 'user,tier'\\n    ]\\n  ]);\\n\\n  $result = $response->json();\\n\\n} catch (Exception $e) {\\n\\n  //error\\n  $result = $e->getResponse()->json();\\n\\n}\",\n      \"language\": \"php\"\n    },\n    {\n      \"code\": \"https://gamewisp.com/api/pub/v1/channel/information?access_token=CHANNEL_ACCESS_TOKEN&include=user,tier&limit=1\",\n      \"language\": \"text\",\n      \"name\": \"Sample URL\"\n    }\n  ]\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"result\\\": {\\n    \\\"status\\\": 1,\\n    \\\"message\\\": \\\"Subscribers Retrieved\\\"\\n  },\\n  \\\"data\\\": [\\n    {\\n      \\\"id\\\": 26,\\n      \\\"user_id\\\": 87545,\\n      \\\"status\\\": \\\"active\\\",\\n      \\\"subscribed_at\\\": null,\\n      \\\"tier_id\\\": \\\"3\\\",\\n      \\\"tier\\\": {\\n        \\\"data\\\": {\\n          \\\"id\\\": 3,\\n          \\\"level\\\": 1,\\n          \\\"title\\\": \\\"Tier title\\\",\\n          \\\"description\\\": \\\"Tier descriptoin.\\\",\\n          \\\"cost\\\": \\\"$3.50\\\",\\n          \\\"published\\\": true,\\n          \\\"created_at\\\": \\\"2015-11-30 00:00:00\\\",\\n          \\\"updated_at\\\": \\\"2015-12-15 03:04:12\\\"\\n        }\\n      },\\n      \\\"user\\\": {\\n        \\\"data\\\": {\\n          \\\"id\\\": 87545,\\n          \\\"username\\\": \\\"test\\\",\\n          \\\"banned\\\": false,\\n          \\\"deactivated\\\": false,\\n          \\\"created_at\\\": \\\"2015-11-10 00:00:00\\\",\\n          \\\"links\\\": {\\n            \\\"uri\\\": \\\"/user/87545\\\"\\n          }\\n        }\\n      }\\n    }\\n  ],\\n  \\\"meta\\\": {\\n    //meta info, cursor, etc.\\n  }\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\nFinally, you can access nested objects using the ```.``` operator. For example, if you would like to return a user's profile picture with their profile object from the [/user/information](https://gamewisp.readme.io/docs/userinformation)endpoint, you would request it as follows:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"var params = {\\n  access_token: \\\"SUBSCRIBER_ACCESS_TOKEN\\\",\\n  include: 'profile.picture'\\n};\\n\\n$.getJSON('https://api.gamewisp.com/pub/v1/user/information/', params, function(json) {\\n    console.log(json);\\n});\",\n      \"language\": \"javascript\",\n      \"name\": \"JavaScript\"\n    }\n  ]\n}\n[/block]\nUsing 'profile.picture' will return the profile picture object nested within the profile object. The ```.``` operator can be used in included strings that also utilize the ```,``` operator.","excerpt":"Some endpoints allow you to get extra information if needed. Here's a brief discussion about how that works.","slug":"additional-includes","type":"basic","title":"Additional Includes"}

Additional Includes

Some endpoints allow you to get extra information if needed. Here's a brief discussion about how that works.

Some of the REST API endpoints allow you to pass in additional information in an ```include``` parameter. This parameter is used to request additional data that may be nested within a JSON response. **For example, here's the /channel/subscribers endpoint JSON with no ```include``` parameter:** [block:code] { "codes": [ { "code": "var params = {\n access_token: \"CHANNEL_ACCESS_TOKEN\",\n limit: 1,\n};\n\n$.getJSON('https://gamewisp.com/api/pub/v1/channel/subscribers/', params, function(json) {\n console.log(json);\n});", "language": "javascript" }, { "code": "<?php\n\n$client = new GuzzleHttp\\Client();\n\ntry {\n\n $response = $client->get('https://gamewisp.com/api/pub/v1/channel/subscribers', [\n 'query' => [\n 'access_token' => 'CHANNEL_ACCESS_TOKEN',\n 'limit': 1,\n ]\n ]);\n\n $result = $response->json();\n\n} catch (Exception $e) {\n\n //error\n $result = $e->getResponse()->json();\n\n}", "language": "php" }, { "code": "https://gamewisp.com/api/pub/v1/channel/information?access_token=CHANNEL_ACCESS_TOKEN&limit=1", "language": "text", "name": "Sample URL" } ] } [/block] [block:code] { "codes": [ { "code": "{\n \"result\": {\n \"status\": 1,\n \"message\": \"Subscribers Retrieved\"\n },\n \"data\": [\n {\n \"id\": 26,\n \"user_id\": 87545,\n \"status\": \"active\",\n \"subscribed_at\": null,\n \"tier_id\": \"3\",\n }\n ],\n \"meta\": {\n //...meta information, cursor, etc.\n }\n }\n}", "language": "json" } ] } [/block] The above ```data``` object includes the ```user_id``` property which defines the user id of the subscriber. This is an acceptable return, but annoying if you have to hit a separate endpoint just to get the user information for this subscriber. [block:api-header] { "type": "basic", "title": "Working with the include Parameter" } [/block] [block:callout] { "type": "info", "title": "Accepted Includes Vary by Endpoint", "body": "If an endpoint accepts an ```include``` parameter, it will be indicated on that particular endpoint's documentation page." } [/block] **Instead of making mutiple API calls to difference resources, you can use the ```include``` parameter to immediately get a nested resource. Like so:** [block:code] { "codes": [ { "code": "var params = {\n access_token: \"CHANNEL_ACCESS_TOKEN\",\n include: \"user\"\n limit: 1,\n};\n\n$.getJSON('https://gamewisp.com/api/pub/v1/channel/subscribers/', params, function(json) {\n console.log(json);\n});", "language": "javascript" }, { "code": "<?php\n\n$client = new GuzzleHttp\\Client();\n\ntry {\n\n $response = $client->get('https://gamewisp.com/api/pub/v1/channel/subscribers', [\n 'query' => [\n 'access_token' => 'CHANNEL_ACCESS_TOKEN',\n 'limit'=> 1,\n 'include' => 'user'\n ]\n ]);\n\n $result = $response->json();\n\n} catch (Exception $e) {\n\n //error\n $result = $e->getResponse()->json();\n\n}", "language": "php" }, { "code": "https://gamewisp.com/api/pub/v1/channel/information?access_token=CHANNEL_ACCESS_TOKEN&include=user&limit=1", "language": "text", "name": "Sample URL" } ] } [/block] And receive the user object for each subscriber returned in the response: [block:code] { "codes": [ { "code": "{\n \"result\": {\n \"status\": 1,\n \"message\": \"Subscribers Retrieved\"\n },\n \"data\": [\n {\n \"id\": 26,\n \"user_id\": 87545,\n \"status\": \"active\",\n \"subscribed_at\": null,\n \"tier_id\": \"3\",\n \"user\": {\n \"data\": {\n \"id\": 87545,\n \"username\": \"test\",\n \"banned\": false,\n \"deactivated\": false,\n \"created_at\": \"2015-11-10 00:00:00\",\n \"links\": {\n \"uri\": \"/user/87545\"\n }\n }\n }\n }\n ],\n \"meta\": {\n //meta information ...cursor, etc.\n }\n }\n}", "language": "json" } ] } [/block] [block:api-header] { "type": "basic", "title": "Advanced include Parameter Usage" } [/block] It's possible to use multiple includes when available. For example, the /channel/subscribers endpoint can accept **user**, **tier**, or even a combination of both separated by a comma (e.g., **'user,tier'**) as a valid include parameter. [block:code] { "codes": [ { "code": "var params = {\n access_token: \"CHANNEL_ACCESS_TOKEN\",\n include: \"user, tier\"\n limit: 1,\n};\n\n$.getJSON('https://gamewisp.com/api/pub/v1/channel/subscribers/', params, function(json) {\n console.log(json);\n});", "language": "javascript" }, { "code": "<?php\n\n$client = new GuzzleHttp\\Client();\n\ntry {\n\n $response = $client->get('https://gamewisp.com/api/pub/v1/channel/subscribers', [\n 'query' => [\n 'access_token' => 'CHANNEL_ACCESS_TOKEN',\n 'limit'=> 1,\n 'include' => 'user,tier'\n ]\n ]);\n\n $result = $response->json();\n\n} catch (Exception $e) {\n\n //error\n $result = $e->getResponse()->json();\n\n}", "language": "php" }, { "code": "https://gamewisp.com/api/pub/v1/channel/information?access_token=CHANNEL_ACCESS_TOKEN&include=user,tier&limit=1", "language": "text", "name": "Sample URL" } ] } [/block] [block:code] { "codes": [ { "code": "{\n \"result\": {\n \"status\": 1,\n \"message\": \"Subscribers Retrieved\"\n },\n \"data\": [\n {\n \"id\": 26,\n \"user_id\": 87545,\n \"status\": \"active\",\n \"subscribed_at\": null,\n \"tier_id\": \"3\",\n \"tier\": {\n \"data\": {\n \"id\": 3,\n \"level\": 1,\n \"title\": \"Tier title\",\n \"description\": \"Tier descriptoin.\",\n \"cost\": \"$3.50\",\n \"published\": true,\n \"created_at\": \"2015-11-30 00:00:00\",\n \"updated_at\": \"2015-12-15 03:04:12\"\n }\n },\n \"user\": {\n \"data\": {\n \"id\": 87545,\n \"username\": \"test\",\n \"banned\": false,\n \"deactivated\": false,\n \"created_at\": \"2015-11-10 00:00:00\",\n \"links\": {\n \"uri\": \"/user/87545\"\n }\n }\n }\n }\n ],\n \"meta\": {\n //meta info, cursor, etc.\n }\n}", "language": "json" } ] } [/block] Finally, you can access nested objects using the ```.``` operator. For example, if you would like to return a user's profile picture with their profile object from the [/user/information](https://gamewisp.readme.io/docs/userinformation)endpoint, you would request it as follows: [block:code] { "codes": [ { "code": "var params = {\n access_token: \"SUBSCRIBER_ACCESS_TOKEN\",\n include: 'profile.picture'\n};\n\n$.getJSON('https://api.gamewisp.com/pub/v1/user/information/', params, function(json) {\n console.log(json);\n});", "language": "javascript", "name": "JavaScript" } ] } [/block] Using 'profile.picture' will return the profile picture object nested within the profile object. The ```.``` operator can be used in included strings that also utilize the ```,``` operator.