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​

Now, 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​

Finally, 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
      }
    }
  }
}