Pagination

Many of the functions in the SDK that return an array of results can be automatically paginated. The VoiceLayer API provides the URLs required for pagination in the Link header that is returned from the server. The functions that support pagination do so via an optional page argument. These functions also support a pages argument in the callback.

One function that supports pagination is the currentUser.getChannels function. If this function is called without a page option then no page parameters will be passed to the server, however the pages argument will still be available in the callback:

voicelayer.currentUser.getChannels(function(err, data, pages) {
  console.log(pages);
});

The pages argument (which will be null if there are no more pages) contains an object like the following:

{
  next: {
    url: https://apiv3.voicelayer.io/v1/channels?page=2&page_size=30,
    page: 2,
    pageSize: 30
  },
  last: {
    url: https://apiv3.voicelayer.io/v1/channels?page=10&page_size=30,
    page: 10,
    pageSize: 30
  }
}

Since the page returned is the first page, only next and last are returned. However if page 5 was returned then the pages object would look like:

{
  next: {
    url: https://apiv3.voicelayer.io/v1/channels?page=6&page_size=30,
    page: 6,
    pageSize: 30
  },
  prev: {
    url: https://apiv3.voicelayer.io/v1/channels?page=4&page_size=30,
    page: 4,
    pageSize: 30
  },
  first: {
    url: https://apiv3.voicelayer.io/v1/channels?page=1&page_size=30,
    page: 1,
    pageSize: 30
  }
  last: {
    url: https://apiv3.voicelayer.io/v1/channels?page=10&page_size=30,
    page: 10,
    pageSize: 30
  }
}

One of these pages can be passed to the currentUser.getChannels function to get the next page. For example:

var channels = [];
function fetchChannels(page) {
  voicelayer.currentUser.getChannels(function(err, data, pages) {
    channels = channels.concat(data);
    if (pages && pages.next) {
      fetchChannels(pages.next);
    }
  }, page);
}

The function will recursively append users channels until all the channels for the user have been fetched.

If no url is present in the page then the page and pageSize properties (both optional) will be used instead. Here is an example to fetch all the channels, 5 at a time, starting at page 3.

var channels = [];
function fetchChannels(page) {
  voicelayer.currentUser.getChannels(function(err, data, pages) {
    channels = channels.concat(data);
    if (pages && pages.next) {
      fetchChannels(pages.next);
    }
  }, page || {page: 3, pageSize: 5});
}

All of the functions that support pagination will have an optional page argument as the last argument of the function.

The channels.getMessages function behaves slightly differently to the others as message pagination works based on the message id instead of the page. This is because new messages can be sent frequently, so by the time you are ready to fetch the next page, it could be a completely different set of results.

The messages pages argument looks has the following structure:

{
  next: {
    url: https://apiv3.voicelayer.io/v1/channels/a6a82017-baf8-49ee-860b-6489745a4d56/messages?before=d508603e-3433-4fce-9f2d-71bfe9cb805f&page_size=30,
    before: d508603e-3433-4fce-9f2d-71bfe9cb805f,
    pageSize: 30
  }
}

Although it has different properties, the usage is the same as the channels example above.