Skip to main content

Pagination

Break down large sets of data retrieved by the API into smaller, more manageable chunks.

Pagination in Swan's API follows the GraphQL Cursor Connections Specification from Relay. Consider reading Relay's specifications for a full explanation.

Elements

An element is a single item in your list. You can always add the optional totalCount object, or the total number of elements in your list. By default, the Swan API returns a list of 20 elements at a time.

Connections

Connections are GraphQL objects that must have edges and pageInfo. They can also have other optional fields.

Edges

Edges are edge types, and are GraphQL objects.

The edges field returns a list defined by the edge type with the following required fields:

  • node: returns a scalar, enum, object, interface, union, or a non-null wrapper around one of those types; can't return a list
  • cursor: returns a type that serializes as a string (example: custom scalar that serializes as a string)

PageInfo

The pageInfo field returns a non-null pageInfo object with the following required fields:

  • hasPreviousPage, hasNextPage: non-null Booleans (must be true or false)
  • startCursor, endCursor: opaque strings, can be null

Arguments

When a field returns a connection type, it must also return a forward pagination argument. These arguments define the edges required for all connections.

Note that after requires an index, which is a unique reference to a specific element in string form. Specifically, the index is a cursor type.

  • first: takes a non-negative integer n and loads only the first n elements from your list (maximum: 100)
  • before: loads all elements occurring before the provided index

Examples

Take the accountMembership query as an example.

Example 1: Use first argument

Imagine you want to retrieve the most recent account to which you became an account member.

Use the forward argument first and the positive integer 1. Submit the query as follows.

Note the returned account number (line 24) and the cursor or index (line 27).

🔎 Open the query in API Explorer

MembershipsFirst1
query FirstMembership {
accountMemberships(first: 1) {
edges {
node {
account {
number
}
}
cursor
}
}
}


# Payload

{
"data": {
"accountMemberships": {
"edges": [
{
"node": {
"account": {
"number": "15102197881"
}
},
"cursor": "MmNlMzk2OT=="
}
]
}
}
}

Example 2: Use index cursor

Add the index to list the 10 account memberships from before the indexed membership. This query would return a long list, so the payload isn't included here.

🔎 Open the query in API Explorer

MembershipsIndex
query TenBefore {
accountMemberships(first: 10, before: "MmNlMzk2OT==") {
edges {
node {
account {
number
}
}
cursor
}
}
}

Example 3: Use pageInfo field

Add pageInfo to know if there are more pages of account memberships.

🔎 Open the query in API Explorer

MembershipsPageInfo
query PageInfo {
accountMemberships(first: 2) {
totalCount
edges {
node {
account {
number
}
}
cursor
}
pageInfo {
endCursor
hasNextPage
}
}
}

# Payload

{
"data": {
"accountMemberships": {
"totalCount": 8,
"edges": [
{...} # list of account memberships
],
"pageInfo": {
"endCursor": $OPAQUE_STRING,
"hasNextPage": true
}
}
}
}