Pagination

Graph API Pagination

The GoToab Graph API supports pagination via Connections.

The gist of a Connection is that it is a GraphQL type that enables pagination by returning metadata fields. Such as, the total number of results, as well as a cursor, that can be passed into subsequent queries to fetch the next or previous set of results.

The default return value for most queries is a Connection type.

If you prefer, there is also the List type, usually just the resource name, i.e. locations, with the word List appended to it, locationsList, and can be used to retrieve a flatter data structure in systems where it's necessary. For the most part cursor-based pagination is the preferred method of accessing resources through the GoTab API.

These Connections conform to the Relay GraphQL Cursor Connections Specification so any relay compatible client should be able to use these connections.

Many GraphQL clients have abstractions and utilities that make dealing with cursor-based pagination automatic and easy, so we would recommend looking into them if possible.

Manual Implementation

If your client does not automatically support pagination then it is still fairly easy to use the cursors.The basic idea is to hold onto the cursor and pass it into your next query.

So given a query such as this:

query paginatedTabs($limit: Int, $cursor: Cursor, $createdAfter: Datetime) {
  tabs(
    first: $limit
    after: $cursor
    filter: { created: { greaterThanOrEqualTo: $createdAfter } }
  ) {
    nodes {
      name
      tabUuid
      created
    }
    pageInfo {
      startCursor
      endCursor
      hasNextPage
      hasPreviousPage
    }
  }
}

To start with you should pass in a 'cursor' variable of 'null'. Your variables object would look similar to...

{
  "createdAfter": "2021-9-15",
  "limit": 25,
  "cursor": null
}

...and you should expect to see a result similar to this.

{
  "data": {
    "tabs": {
      "nodes": [
        // ...list of tabs
      ],
      "pageInfo": {
        "startCursor": "WyJwcmltYXJ5X2tleV9hc2MiLFs4NjAyNzMyXV0=",
        "endCursor": "WyJwcmltYXJ5X2tleV9hc2MiLFs4NjAyNzMyXV0=",
        "hasNextPage": true,
        "hasPreviousPage": false
      }
    }
  }
}

From here you can take the endCursor and pass it into the same query to get the next set of results. Your updated variables object would then look like:

{
  "createdAfter": "2021-9-15",
  "limit": 25,
  "cursor": "WyJwcmltYXJ5X2tleV9hc2MiLFs4NjAyNzMyXV0="
}