How pagination has been implemented in our GraphQL API
Pagination is a basic feature for browsing lists returned by an API and definitely plays an important role in the overall developer experience. With its flexible nature, GraphQL lets you decide how to implement pagination according to your requirements.
This freedom to choose can also mean a decision-making nightmare!
There are actually many possible solutions as described in this great post, with each solution having its advantages and drawbacks.
Relay pagination
Relay cursor connections pagination is perhaps the most powerful implementation and is a natural choice when using Relay in the front-end.
But it also introduces new concepts as “Connections”, “Edges” and “Nodes”, which can add some friction to the learning curves of developers who use the API and the ones who implement it!
{
user {
id
name
friends (first: 10, after: "opaqueCursor") {
edges {
cursor
node {
id
name
}
}
pageInfo {
totalCount
hasNextPage
hasPreviousPage
}
}
}
}Still, these efforts can be justified by the level of features Relay cursor connections pagination provides, especially when developers use React with Relay.
The relative complexity of this solution was not a reason to choose another one instead, however.
Sometimes you have to decide between perfection and efficiency.
Our objective was to deliver the WorkflowGen GraphQL API in three months — the kind of deadline that really helps to find a way out of the labyrinth of the decision-making process!
Due to our huge existing code base and SQL queries that use a classic page number pagination, we had to skip Relay cursor connections.
We tried to see how far we could go with Relay cursor connections by reusing our existing code, but such an implementation would either have been partial (with no backward navigation) or entail too much effort in rewriting certain SQL queries to support user-defined sort orders compatible with bidirectional cursor-based navigation.
Page number pagination
Our current GraphQL pagination implementation is a classic page number based pagination that has the advantage of being available now for all lists, not to mention straightforward.
We have reused some of Relay’s PageInfo type attributes: totalCount, hasNextPage and hasPreviousPage.
{
viewer {
requests (page: {number: 2, size: 20}) {
totalCount
hasNextPage
hasPreviousPage
items {
id
number
requester {
userName
}
}
}
}
}The corresponding “requests” field definition:
# List of requests.
requests (page: Page, orderBy: RequestListOrder, filter: RequestFilter): RequestListPage!
The Page input type:
# A page.
input Page {
# Identifies the page number.
number: Int,
# Identifies the page size.
size: Int
}
RequestListPage GraphQL type:
# A paginated list of requests.
type RequestListPage {
# Identifies the total count of items in the page.
totalCount: Int!
# Indicates if there are more pages to fetch.
hasNextPage: Boolean!
# Indicates if there are any pages prior to the current page.
hasPreviousPage: Boolean!
# List of requests.
items: [Request]
}
To retrieve the total count without the list of items, you just need to set the page number to 0:
{
viewer {
requests (page: {number: 0}, filter: {as: REQUESTER) {
totalCount
hasNextPage
hasPreviousPage
}
}
}Conclusion
A GraphQL schema can be extended with limited impacts and breaking changes for developers. A page number pagination is simple and intuitive, but doesn’t have some advanced features provided by a cursor-type pagination, so we’re keeping in mind the possibility of delivering Relay cursor connections for some types in future releases.
We also expect a lot of feedback from our customers, and we’ll rely on the “organic” nature of the GraphQL schema to improve our implementation with incremental cycles.
The dawn of GraphQL dialects
GraphQL opens limitless design possibilities, and perhaps in the future, some part of the schema will be standardized (such as a pagination viewer with Relay or schema.org for JSON). This should accelerate API implementation and interoperability, which in turn will free up more time for developers to work on other levels of features.
GraphQL API pagination implementation was originally published in WorkflowGen on Medium, where people are continuing the conversation by highlighting and responding to this story.