Pagination

Revision as of 16:16, 16 June 2015

Large resources lists require pagination. Pagination is controlled by two query parameters, page and pageSize. If they are not specified (meaning, the client is requesting the full list), the API will attempt to return the full list. If there are more than 100 elements in the full list, the API will instead return a response code of 303 "See Other", with a Location header in the response containing the URL for the first page of the equivalent paginated call (where pageSize = 100).

GET /<url>?page=1&pageSize=20

page

Optional The 1-based index of the page of results requested. page is required if pageSize has been provided.

pageSize

Optional The maximum number of resources to be returned on each page of the paginated request. This value cannot currently exceed 400; any requests with pageSize > 400 will result in a response code of 303 "See Other", with a Location header in the response containing the URL for the same page of a paginated call with pageSize=400. pageSize is required if page has been provided.

Sample response

{
  "list": [
    {... resource 1 ...},
    {... resource 2 ...},
    ...
  ],
  "links": [
    {"rel": "self", "href": "/<url>?page=5&pageSize=20"},
    {"rel": "previous", "href": "/<url>?page=4&pageSize=20"},
    {"rel": "first", "href": "/<url>?page=1&pageSize=20"},
    {"rel": "next", "href": "/<url>?page=6&pageSize=20"},
    {"rel": "last", "href": "/<url>?page=231&pageSize=20"},
  ]
}
 

The previous and first links will be omitted if the current page is the first page, and the next and last links will be omitted if the current page is the last page.

See also

• Common Features