Pagination of API Results

Working with API result-sets containing multiple entities.

Some queries made to the GraphQL API may result in a large amount of entities returned from the server. To prevent crippling amounts of data being exchanged between the server and the client, most GraphQL resolvers which may return a list of multiple entities will only return a subset of the full set of results. In addition to the results, it will also return a so-called cursor, which can be used in subsequent queries to get more results. Splitting up the full set of results into multiple "pages" using this method is known as pagination.

Example

Consider the following query:

{
  flights(from: "2012-01-01", to: "2022-12-31") {
    nodes {
      aircraft {
        id
          callSign
      }
    }
  }
}

The query will select all bookings from the beginning of 2012 to the end of 2022. 10 years, that's a lot of bookings! Because of this, the response from the server will only contain some of the bookings within said time-span.

To get the next "page" of bookings, some additional information needs to be selected in the query, under the pageInfo field, namely hasNextPage and endCursor:

{
  flights(from: "2012-01-01", to: "2022-12-31") {
    pageInfo {
      hasNextPage
      endCursor
    }
    nodes {
      aircraft {
        id
          callSign
      }
    }
  }
}

hasNextPage is a boolean value which, when true, indicates that the set of results returned is incomplete, and there are more results to be fetched.

endCursor is a string value which may be passed to the next query in order to fetch the next page of results. It is tied to the last element of the set of results returned.

If we want more of the results, we simply pass the value of endCursor from the last response into the query of the next request via the after argument of the resolver:

{
  flights(from: "2012-01-01", to: "2022-12-31", after: "NTA") {
    pageInfo {
      hasNextPage
      endCursor
    }
    nodes {
      aircraft {
        id
          callSign
      }
    }
  }
}

This operation may then be repeated with the endCursor value of the latest response until hasNextPage is false to get the full set of results.

Reliability

It should be noted that pagination will only work as expected when used with identical resolver arguments. This means changing arguments of the resolver, like the sorting or filtering for instance, between queries may result in missed or duplicate entities in the set of results. In almost all cases, the only argument which should change between queries is the after argument of the resolver.