API Basics

Modified on Mon, 24 Mar at 1:11 PM

Pagination

All GET endpoints have pagination and sorting support. The pagination is cursor-based and the parameters are first (integer) and after (string). If none are supplied the API returns a default number of results from the beginning using a default sort. The default number of results varies per operation.

An example using pagination

The authorization header has been removed to keep it simple and responses have been simplified.

GET /years

Returns a response looking something like this:

{
    "totalCount": 4,
    "pageInfo": {
        "hasNextPage": true,
        "startCursor": "aWR4OzA=",
        "endCursor": "aWR4OzE="
    },
    "items": [
        {
            "cursor": "aWR4OzA=",
            "node": {
                "name": "2017"
            }
        },
        {
            "cursor": "aWR4OzE=",
            "node": {
                "name": "2018"
            }
        }
    ]
}

All responses have the same structure to help with pagination.

Property	Description
totalCount	The total number of the resource
pageInfo.hasNextPage	True if there are more pages
pageInfo.startCursor	The start cursor of the page
pageInfo.endCursor	The end cursor of the page
items	Array of items returned
item.cursor	The cursor of the item
item.node	The actual resource of the item

Since pageInfo.hasNextPage is true we know that there is more data to collect. This time we will use the after parameter to indicate we want to start at a specific position.

GET /years?first=2&after=aWR4OzE=

Returns a response like this

{
"totalCount": 4,
"pageInfo": {
"hasNextPage": false,
"startCursor": "aWR4OzI=",
"endCursor": "aWR4OzM="
},
"items": [
{
"cursor": "aWR4OzI=",
"node": {
"name": "2019"
}
},
{
"cursor": "aWR4OzM=",
"node": {
"name": "2020"
}
}
]
}

The pageInfo.hasNextPage is false so we have no more data to get.

Error response

If the request is invalid the API will respond with status code 400 and an error response. The error response contains an error property which is an array of error descriptions.

Property	Description
property	Name of the property the error concerns
errorMessage	The error message, what is wrong
suggestion	What should be changed

Example of an error response when using 510 as a value for a first parameter.

{
    "errors": [
        {
            "property": "first",
            "errorMessage": "510 invalid value",
            "suggestion": "Must be between 1 and 100"
        }
    ]
}