Many API services return paginated lists of objects. We follow a consistent convention for all of our lists, which is compatible with the Mason format. Following is an example list output:

{
    "filters": {},
    "sort": {},
    "total": 42,
    "offset": 0,
    "limit": 3,
    "items": [
        {
            "id": 123,
            "name": "Human"
        },
        {
            "id": 456,
            "name": "Vulcan"
        },
        {
            "id": 789,
            "name": "Ferengi"
        }
    ]
}

Each property is defined below.

Property

Data Type

Description

filters

Object

Filter options that were requested, if any. See List Inputs for details.

sort

Object

Sorting options that were requested, if any. See List Inputs for details.

total

Integer

Grand total of all items found

offset

Integer

Number of items skipped. See List Inputs for details.

limit

Integer

Maximum number of items shown in this page of results. See List Inputs for details.

items

Array

List of objects included in this page of results