GraphQL - Cursor Based Pagination

1

Understanding the Pagination Parameters

Our GraphQL API uses the following pagination parameters:

• first: The number of items to return in a single response.
• after: A unique identifier for the last item returned.

Our GraphQL APIs returns the following pagination informations :

• PageInfo : contains information about the pagination of the whole request, based on non-pagination parameters.
• endCursor : located in the PageInfo, refers to the last cursor of the result.

The idea of the Partial Pagination is to request for another page if the number of results was equal to the number requested (thanks to the firstparameter). If the number of result was smaller than the number requested, it means that there is no more data matching the parameters.

Basically, the cursor of the last node (conveniently the endCursor) should be used in the after parameter if the result returned were equal to first parameter.

2

Making an Initial Request

To start using pagination, make an initial request to our API without providing a cursor. This will return the first page of results along with the cursor for the last item.

Example (using GraphQL query)

 
query {  
    items(first: 3) {
        pageInfo {
            endCursor
        }
        edges {
            node {
                id    
                name
            }
        }
    }
}

We are requesting for the first 3 items to be returned, along with the PageInfo object. We do not need to request for the cursor of the nodes, since the endCursor is enough to request for the next page.

3

Checking for returned items

Check if there are more results available by examining the response. If the number of returned items is equal to the provided parameter first, then it's very likely that there are more items matching the same criterias..

Example of a response

 
{
    "data": {
        "items": {
            "pageInfo": {
                "endCursor": "MA=="
            },
            "edges": [
                {
                    "node": {
                        "id": 01
                        "name": "example"
                     }
                 },
                 {
                    "node": {
                        "id": 02
                        "name": "example"
                     }
                 }
             ]
         }
     }         
}
            
    

4

Passing the Cursor

Locate the received endCursor . In the subsequent request, pass this cursor to our API using the after parameter.

Example (using GraphQL query)

 
query {    
    items(first: 10, after: "MA==") {
        pageInfo {
            endCursor
        }
        edges {
            node {
                id
                name
            }
        }
    }
}