Pagination - Contento

Whenever you request a list of objects you will receive a paginated response.

There are two types of pagination available - by default the API will use cursor pagination, but you can also turn on simple pagination and request specific pages by their page number.

Single object responses

If the response contains only one object then a paginated response will not be returned, instead the entire response will be a single object.

This can happen if you set the limit parameter to 1 or if the resulting dataset based on your query parameters results in a single object.

Cursor pagination (default)

Cursor pagination is faster, and most useful when you just need to get the whole dataset for further processing or simply create a "show more posts" type of experience.

It works by creating an encoded string containing the location and direction that the next paginated query should start from.

The only downside is you can’t know the number of pages in the dataset when you get a response, so if you need to know that then use simple pagination instead.

Request

GET https://app.contento.io/api/v1/content HTTP/1.1
Authorization: Bearer {token}
X-CONTENTO-SITE: {site_id}

Parameters

All the usual parameters are available with paginated requests, the ones that affect pagination directly are listed here:

Parameter	Format	Default	Accepted values
`cursor`	`String`		Cursor string e.g. `eyJwdWJsaXNoZWRfYXQiOiIyMDIyLTA2LTA3IDExOjU0OjI5IiwiX3BvaW50c1RvTmV4dEl0ZW1zIjpmYWxzZX0`.
`limit`	`Integer`	`20`	The number of results you want in the response.
`sort`	`String` or `Array`	`published_at:desc`	You must supply values in the following format: `attribute:direction` — read more.

Response

There will be a top level data key that contains the objects you have requested, and then links and meta keys containing the pagination information.

The whole response will look a little something like this:

{
  "data": [ 
    ...
  ],
  "links": {
    "first": null,
    "last": null,
    "prev": "https://app.contento.io/api/v1/content?cursor=eyJwdWJsaXNoZWRfYXQiOiIyMDIyLTA2LTA3IDExOjU0OjI5IiwiX3BvaW50c1RvTmV4dEl0ZW1zIjpmYWxzZX0",
    "next": "https://app.contento.io/api/v1/content?cursor=eyJwdWJsaXNoZWRfYXQiOiIyMDIyLTA2LTA3IDExOjU0OjI5IiwiX3BvaW50c1RvTmV4dEl0ZW1zIjp0cnVlfQ"
  },
  "meta": {
    "path": "https://app.contento.io/api/v1/content",
    "per_page": 20,
    "next_cursor": "eyJwdWJsaXNoZWRfYXQiOiIyMDIyLTA2LTA3IDExOjU0OjI5IiwiX3BvaW50c1RvTmV4dEl0ZW1zIjp0cnVlfQ",
    "prev_cursor": "eyJwdWJsaXNoZWRfYXQiOiIyMDIyLTA2LTA3IDExOjU0OjI5IiwiX3BvaW50c1RvTmV4dEl0ZW1zIjpmYWxzZX0"
  }
}

`links`

Provides an interface for quickly getting the previous or next request in the paginated set. URLs will have their cursor parameter set to the correct value and any other parameters that are present in the request will remain in place.

Attribute	Type	Description
`first`	`null`	Not in use.
`last`	`null`	Not in use.
`prev`	`String` or `null`	URL for the previous request in the paginated set.
`next`	`String` or `null`	URL for the next request in the paginated set.

Example:

{
  "first": null,
  "last": null,
  "prev": "https://app.contento.io/api/v1/content?cursor=eyJwdWJsaXNoZWRfYXQiOiIyMDIyLTA2LTA3IDExOjU0OjI5IiwiX3BvaW50c1RvTmV4dEl0ZW1zIjpmYWxzZX0",
  "next": "https://app.contento.io/api/v1/content?cursor=eyJwdWJsaXNoZWRfYXQiOiIyMDIyLTA2LTA3IDExOjU0OjI5IiwiX3BvaW50c1RvTmV4dEl0ZW1zIjp0cnVlfQ"
}

`meta`

Details of the pagination configuration for this request.

Attribute	Type	Description
`path`	`String`	The base URI path of the API endpoint being requested.
`per_page`	`Integer`	Set to the value of the `limit` parameter on the request.
`next_cursor`	`String` or `null`	Cursor value for the next request in the paginated set.
`prev_cursor`	`String` or `null`	Cursor value for the previous request in the paginated set.

Example:

{
  "path": "https://app.contento.io/api/v1/content",
  "per_page": 20,
  "next_cursor": "eyJwdWJsaXNoZWRfYXQiOiIyMDIyLTA2LTA3IDExOjU0OjI5IiwiX3BvaW50c1RvTmV4dEl0ZW1zIjp0cnVlfQ",
  "prev_cursor": "eyJwdWJsaXNoZWRfYXQiOiIyMDIyLTA2LTA3IDExOjU0OjI5IiwiX3BvaW50c1RvTmV4dEl0ZW1zIjpmYWxzZX0"
}

Simple pagination

Simple pagination works by requesting the specific page you want to view via the page query parameter.

You can switch simple pagination on by setting the X-CONTENTO-SIMPLE-PAGINATION header to true for all requests that require it:

Request

GET https://app.contento.io/api/v1/content HTTP/1.1
Authorization: Bearer {token}
X-CONTENTO-SITE: {site_id}
X-CONTENTO-SIMPLE-PAGINATION: true

Parameters

As with cursor pagination the usual parameters are available with the request, the ones that affect simple pagination directly are listed here:

Parameter	Format	Default	Accepted values
`limit`	`Integer`	`20`	The number of results you want in the response.
`page`	`Integer`		The page number you want to fetch e.g. `2`.
`sort`	`String` or `Array`	`published_at:desc`	You must supply values in the following format: `attribute:direction` — read more.

Response

The top level structure of the response is the same as the cursor pagination response, however the internal structure of the links and meta keys will be different.

The whole response for a request with page=2 will look a little something like this:

{
  "data": [ 
    ...
  ],
  "links": {
    "first": "https://app.contento.io/api/v1/content?page=1",
    "last": "https://app.contento.io/api/v1/content?page=33",
    "prev": "https://app.contento.io/api/v1/content?page=1",
    "next": "https://app.contento.io/api/v1/content?page=3"
  },
  "meta": {
    "current_page": 2,
    "from": 21,
    "last_page": 33,
    "links": [
      {
        "url": "https://app.contento.io/api/v1/content?page=1",
        "label": "&laquo; Previous",
        "active": false
      },
      {
        "url": "https://app.contento.io/api/v1/content?page=1",
        "label": "1",
        "active": false
      },
      {
        "url": "https://app.contento.io/api/v1/content?page=2",
        "label": "2",
        "active": true
      },
      {
        "url": "https://app.contento.io/api/v1/content?page=3",
        "label": "3",
        "active": false
      },
      {
        "url": "https://app.contento.io/api/v1/content?page=4",
        "label": "4",
        "active": false
      },
      {
        "url": "https://app.contento.io/api/v1/content?page=5",
        "label": "5",
        "active": false
      },
      {
        "url": "https://app.contento.io/api/v1/content?page=6",
        "label": "6",
        "active": false
      },
      {
        "url": "https://app.contento.io/api/v1/content?page=7",
        "label": "7",
        "active": false
      },
      {
        "url": "https://app.contento.io/api/v1/content?page=8",
        "label": "8",
        "active": false
      },
      {
        "url": "https://app.contento.io/api/v1/content?page=9",
        "label": "9",
        "active": false
      },
      {
        "url": "https://app.contento.io/api/v1/content?page=10",
        "label": "10",
        "active": false
      },
      {
        "url": null,
        "label": "...",
        "active": false
      },
      {
        "url": "https://app.contento.io/api/v1/content?page=32",
        "label": "32",
        "active": false
      },
      {
        "url": "https://app.contento.io/api/v1/content?page=33",
        "label": "33",
        "active": false
      },
      {
        "url": "https://app.contento.io/api/v1/content?page=3",
        "label": "Next &raquo;",
        "active": false
      }
    ],
    "path": "https://app.contento.io/api/v1/content",
    "per_page": 20,
    "to": 40,
    "total": 657
  }
}

`links`

Provides an interface for quickly getting the first, last previous or next request in the paginated set. URLs will have their page parameter set to the correct value and any other parameters that are present in the request will remain in place.

Attribute	Type	Description
`first`	`String` or `null`	URL for the first request in the paginated set.
`last`	`String` or `null`	URL for the last request in the paginated set.
`prev`	`String` or `null`	URL for the previous request in the paginated set.
`next`	`String` or `null`	URL for the next request in the paginated set.

Example:

{
  "first": "https://app.contento.io/api/v1/content?page=1",
  "last": "https://app.contento.io/api/v1/content?page=33",
  "prev": "https://app.contento.io/api/v1/content?page=1",
  "next": "https://app.contento.io/api/v1/content?page=3"
}

`meta`

Details of the pagination configuration for this request.

Attribute	Type	Description
`current_page`	`Integer`	The number for the current page in the response.
`from`	`Integer`	The position in the total dataset of the first object in this response.
`last_page`	`Integer`	The number for the last page available in the dataset.
`links`	`Array`	An array of `link` objects.
`path`	`String`	The base API path the request is for, without any parameters.
`per_page`	`Integer`	The number of objects in each page, this matches whatever `limit` is set to which by default is `20`.
`to`	`Integer`	The position in the total dataset of the last object in this response.
`total`	`Integer`	The total number of objects in the requested dataset.

Example:

{
  "current_page": 2,
  "from": 21,
  "last_page": 33,
  "links": [
    ...
  ],
  "path": "https://app.contento.io/api/v1/content",
  "per_page": 20,
  "to": 40,
  "total": 657
}

`link`

Link objects are only ever returned as part of the meta.links attribute on a simple pagination request. They can be useful for building pagination UI with previous, next and numbered page links.

They have the following attributes:

Attribute	Type	Description
`url`	`String` or `null`	URL for the link.
`label`	`String`	A human readable label for the link e.g. `2` or `Next »`.
`active`	`Boolean`	Whether this link is the active link for the request.

Example:

{
  "url": "https://app.contento.io/api/v1/content?page=2",
  "label": "2",
  "active": true
}