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 listcursor: 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 integernand loads only the firstnelements 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 in API Explorerquery 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 in API Explorerquery 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.
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
}
}
}
}