Pagination

Toucan public API can provide access to a large amount of information. In some cases, you may find that it returns too much information. In order not to put too much stress on our servers, our API automatically paginates the sent data.

In this article we will see how this pagination works.

Basics of pagination

To begin with, a number of basic things about receiving paged elements:

• You can specify the number of items to return.
• But it is possible that some returns are still limited.

The meta object

Pagination information is returned in a meta structure by relative links.

meta is an object that contains four elements:

Key	Description
page	Current page of the response
limit	Maximum number of elements returned per page.
total	Total number of elements returned on all pages.
lastPage	Last accessible paginated page.

Example

$ curl "https://api-<instance>.toucantoco.com/vO/users"

> {
    "data": [
        ...
    ]
    "meta" : {
        "page": 1,
        "limit": 50,
        "total": 253,
        "lastPage": 6
    }
}

See the meta information?

By default the first page ("page": 1) with 50 elements ("limit": 50) is returned. We know there are 253 users ("total": 253) in our instance hence 6 user pages in total ("lastPage": 6): 5 full pages with 50 users each and the last one with 3.

Accessing a specific page

If you want to access a specific page you can do so by specifying a value to the page parameter in your query.

$ curl "https://api-<instance>.toucantoco.com/vO/users?page=4"

> {
    "data": [
        ...
    ]
    "meta" : {
        "page": 4,
        "limit": 50,
        "total": 253,
        "lastPage": 6
    }
}

Play on maximum elements

If you want to play on the maximum number of elements returned in the response you can do so by specifying a value to the limit query parameter in your query.

Note that changing the limit will naturally also change the lastPage information.

$ curl "https://api-<instance>.toucantoco.com/vO/users?limit=100"

> {
    "data": [
        ...
    ]
    "meta" : {
        "page": 1,
        "limit": 100,
        "total": 253,
        "lastPage": 3
    }
}