PaginatedList (JSON)

Describes paginated lists, a type of response from the Xbox Music Service that can be continued by using a token.

Some of the methods in the Xbox Music RESTful API return lists of elements in their responses (for example, search results, albums of an artist, tracks of an album, and so on). These lists can potentially be very large, so we have put in place a mechanism to paginate these lists by using a continuation token. These lists and tokens are returned in a PaginatedList object.

This topic describes the PaginatedList object and provides examples of its use in the
following sections:

PaginatedList

All the paginated lists in responses from the Xbox Music Service use the same data structure, a
PaginatedList object, which is described in the following table.

Member

Type

Description

Items

list

The items composing the paginated list. When a list is of relatively small size,
Items will contain the full list and ContinuationToken will be null. However,
the list may be incomplete, which is indicated by the value of ContinuationToken.

ContinuationToken

string

An opaque string that may be provided in a subsequent request to the same URL in order to continue the list.
If ContinuationToken is not null, then the list is not complete, and the token
may be used to retrieve the remaining elements.
A null value indicates that the list has no remaining items yet to be returned.

TotalItemCount

integer

An estimated count of the total number of items available in the list.

A continuation token is an opaque string that should never be modified by the client, only passed as-is in subsequent requests. To obtain the continuation of a particular paginated list, the client should call the exact same URL as in the original request whose response produced the continuation token, except that it should add that continuation token in the optional continuationToken query parameter that those APIs support and remove all the other optional API parameters. The response from that call respects the same data structure as the original response, but most of the fields are null to avoid repeating the same information. Only the few fields critical for identification of the item (such as ID) are populated, as is the paginated list that the continuation token applies to. This paginated list contains the elements that immediately follow the ones from the original request. This second paginated list may also itself be incomplete and come with its own continuation token, so the same concept can be applied to more than two pages.