Cursor based Pagination

Poppulo's api follows the relay pagination spec which can be viewed here: https://relay.dev/graphql/connections.htm

Pagination allows the user to traverse the data in pages using cursors (opaque strings). It is a necessity for certain queries to avoid overwhelming the client and server. Each service will define a default limit which is the max number of items which can be returned in a page.

Each page of data will contain some metadata which can be utilized to page forward or back.

Page metadata

PageInfo{
    startCursor
    endCursor
    hasPreviousPage
    hasNextPage
}

The startCursor and endCursor are the cursors for the first and last items on the page. hasPreviousPage and hasNextPage are boolean values which tell the user if there is a previous page or next page available.

Pagination parameters

When making a request the available parameters are as follows.

first:  number of items required.
last:   number of items required.
after:  used to get the next page of data after the specified cursor
before: used to get the previous page of data before the specified cursor

first and last have different behaviours depending on whether they are used with after or before. This will become more clear in the Sample requests section.

Please Note: first and last are mutually exclusive parameters and using them together will result in a 400 response.

Sample requests

For these examples we will assume each objects cursor represents the date of a post. For simplicity this date will just be an integer. So our dataset cursors will be 1 -> 20, representing the posts in ascending order by date.

Here is an example of getting the next page of data. We will assume we have already received the first 10 items and are setting the after parameter as the endCursor (10 in this case).

{
    getPosts(first: 5, after: 10) {
      edges {
        cursor
        node {
          id
          author
        }
      }
      pageInfo {
        startCursor
        endCursor
        hasNextPage
        hasPreviousPage
      }
    }
}

This query will return these edge cursors [11,12,13,14,15] and this pageInfo object

pageInfo {
    startCursor: 11
    endCursor: 15
    hasNextPage: true
    hasPreviousPage: true
}

In the next query we will retrieve the last 2 objects that come directly before the cursor 14.

{
    getPosts(last: 2, before: 14) {
      edges {
        cursor
        node {
          id
          author
        }
      }
      pageInfo {
        startCursor
        endCursor
        hasNextPage
        hasPreviousPage
      }
    }
}

This query will return these edge cursors [12,13] and this pageInfo object

pageInfo {
    startCursor: 12
    endCursor: 13
    hasNextPage: true
    hasPreviousPage: true
}

if we want to get the last item in the dataset we can simply use last

{
    getPosts(last: 1) {
      edges {
        cursor
        node {
          id
          author
        }
      }
      pageInfo {
        startCursor
        endCursor
        hasNextPage
        hasPreviousPage
      }
    }
}

This query will return the edge cursor [20] and this pageInfo object

pageInfo {
    startCursor: 20
    endCursor: 20
    hasNextPage: false
    hasPreviousPage: true
}

Next steps

Complexity Limiting