Pagination

Pagination in the Yonomi platform follows the Relay Connections specification. Refer to the GraphQL Cursor Connections Specification for how this pagination method is used in GraphQL.

Per this specification:

• A paginated response is represented by a Connection, which consists of an edge of nodes.
• A node represents an item, and an edge represents an array of those items.

Currently Yonomi platform only supports forward pagination.

The documentation below describes how the Relay Connections specification is used in Yonomi platform.

Parameters#

In order to paginate the platform relies on a couple of parameters for pagination, first which is an integer and after which is a string representing an opaque cursor.

• The first parameter indicates the number of items to return.
• The after parameter indicates the place in the platform’s items to start pagination at.

The platform is then able to reliably paginate its items with these two pieces of information. These parameters pertain to forward pagination only.

Pagination data#

There are various pieces of data that are associated to pagination that can be queried.

edges and nodes make up the actual data returned.

• node is the actual data that is paginated.
• edges consist of a group of nodes.

pageInfo is pagination metadata that indicates whether there is more data to retrieve. pageInfo may also provide cursors that can be used to retrieve any additional data. pageInfo is itself an object that contains startCursor, endCursor, hasNextPage, and hasPreviousPage fields.

• startCursor is a string that indicates the first cursor that appears in the items that are returned.
• endCursor is a string that indicates the last cursor that appears in the items that are returned.
• hasNextPage is a Boolean that indicates whether there are more items that can be paginated through.
• hasPreviousPage can be ignored since only forward pagination is supported. This value will always be false.

Query#

In the following example the IDs of all devices tied to the current user are retrieved. This shows a GraphQL query that outlines how to utilize pagination. Paginated items must always be queried in this manner.

query {
  me {
    devices (first: 3, after: "opaqueCursor") {
      pageInfo {
        startCursor
        endCursor
        hasNextPage
        hasPreviousPage
      }
      edges {
        node {
          id
        }
      }
    }
  }
}

• devices is a Connection which is passed parameters that control pagination of the query.
• The node itself is a device, and the query only returns the ID of that device.
• The after parameter is only needed on subsequent queries for additional paginated items.

Response#

This outlines an example response resulting from the above query.

{
  "me": {
    "devices": {
      "pageInfo": {
        "startCursor": "opaqueStartCursor",
        "endCursor": "opaqueEndCursor",
        "hasNextPage": true,
        "hasPreviousPage": false
      },
      "edges": [
        {
          "node": {
            "id": "deviceId1"
          }
        },
        {
          "node": {
            "id": "deviceId2"
          }
        },
        {
          "node": {
            "id": "deviceId3"
          }
        }
      ]
    }
  }
}

• The startCursor and endCursor values under pageInfo correspond to the first and last nodes being returned, respectively.
• The hasNextPage value under pageInfo indicates that there are more devices that can be paginated through. Fetching these devices requires more queries like the one above.
• The hasPreviousPage value under pageInfo will always be false since only forward pagination is supported, as mentioned above.
• The edges value will always be an array of nodes. The values of nodes are the items of data queried. In this case, the node values are objects containing the IDs of devices.