Additional Includes

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:

var params = {
  access_token: "CHANNEL_ACCESS_TOKEN",
  limit: 1,
};

$.getJSON('https://gamewisp.com/api/pub/v1/channel/subscribers/', params, function(json) {
    console.log(json);
});

<?php

$client = new GuzzleHttp\Client();

try {

  $response = $client->get('https://gamewisp.com/api/pub/v1/channel/subscribers', [
    'query' => [
      'access_token'  => 'CHANNEL_ACCESS_TOKEN',
      'limit': 1,
    ]
  ]);

  $result = $response->json();

} catch (Exception $e) {

  //error
  $result = $e->getResponse()->json();

}

https://gamewisp.com/api/pub/v1/channel/information?access_token=CHANNEL_ACCESS_TOKEN&limit=1

{
  "result": {
    "status": 1,
    "message": "Subscribers Retrieved"
  },
  "data": [
    {
      "id": 26,
      "user_id": 87545,
      "status": "active",
      "subscribed_at": null,
      "tier_id": "3",
    }
  ],
  "meta": {
    //...meta information, cursor, etc.
   }
  }
}

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.

Working with the include Parameter

📘
Accepted Includes Vary by Endpoint
If an endpoint accepts an include parameter, it will be indicated on that particular endpoint's documentation page.

Instead of making mutiple API calls to difference resources, you can use the include parameter to immediately get a nested resource. Like so:

var params = {
  access_token: "CHANNEL_ACCESS_TOKEN",
  include: "user"
  limit: 1,
};

$.getJSON('https://gamewisp.com/api/pub/v1/channel/subscribers/', params, function(json) {
    console.log(json);
});

<?php

$client = new GuzzleHttp\Client();

try {

  $response = $client->get('https://gamewisp.com/api/pub/v1/channel/subscribers', [
    'query' => [
      'access_token'  => 'CHANNEL_ACCESS_TOKEN',
      'limit'=> 1,
      'include' => 'user'
    ]
  ]);

  $result = $response->json();

} catch (Exception $e) {

  //error
  $result = $e->getResponse()->json();

}

https://gamewisp.com/api/pub/v1/channel/information?access_token=CHANNEL_ACCESS_TOKEN&include=user&limit=1

And receive the user object for each subscriber returned in the response:

{
  "result": {
    "status": 1,
    "message": "Subscribers Retrieved"
  },
  "data": [
    {
      "id": 26,
      "user_id": 87545,
      "status": "active",
      "subscribed_at": null,
      "tier_id": "3",
      "user": {
        "data": {
          "id": 87545,
          "username": "test",
          "banned": false,
          "deactivated": false,
          "created_at": "2015-11-10 00:00:00",
          "links": {
            "uri": "/user/87545"
          }
        }
      }
    }
  ],
  "meta": {
    //meta information ...cursor, etc.
    }
  }
}

Advanced include Parameter Usage

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.

var params = {
  access_token: "CHANNEL_ACCESS_TOKEN",
  include: "user, tier"
  limit: 1,
};

$.getJSON('https://gamewisp.com/api/pub/v1/channel/subscribers/', params, function(json) {
    console.log(json);
});

<?php

$client = new GuzzleHttp\Client();

try {

  $response = $client->get('https://gamewisp.com/api/pub/v1/channel/subscribers', [
    'query' => [
      'access_token'  => 'CHANNEL_ACCESS_TOKEN',
      'limit'=> 1,
      'include' => 'user,tier'
    ]
  ]);

  $result = $response->json();

} catch (Exception $e) {

  //error
  $result = $e->getResponse()->json();

}

https://gamewisp.com/api/pub/v1/channel/information?access_token=CHANNEL_ACCESS_TOKEN&include=user,tier&limit=1

{
  "result": {
    "status": 1,
    "message": "Subscribers Retrieved"
  },
  "data": [
    {
      "id": 26,
      "user_id": 87545,
      "status": "active",
      "subscribed_at": null,
      "tier_id": "3",
      "tier": {
        "data": {
          "id": 3,
          "level": 1,
          "title": "Tier title",
          "description": "Tier descriptoin.",
          "cost": "$3.50",
          "published": true,
          "created_at": "2015-11-30 00:00:00",
          "updated_at": "2015-12-15 03:04:12"
        }
      },
      "user": {
        "data": {
          "id": 87545,
          "username": "test",
          "banned": false,
          "deactivated": false,
          "created_at": "2015-11-10 00:00:00",
          "links": {
            "uri": "/user/87545"
          }
        }
      }
    }
  ],
  "meta": {
    //meta info, cursor, etc.
  }
}

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/informationendpoint, you would request it as follows:

var params = {
  access_token: "SUBSCRIBER_ACCESS_TOKEN",
  include: 'profile.picture'
};

$.getJSON('https://api.gamewisp.com/pub/v1/user/information/', params, function(json) {
    console.log(json);
});

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.

Working with the include Parameter

📘Accepted Includes Vary by Endpoint

Advanced include Parameter Usage

📘
Accepted Includes Vary by Endpoint