GraphQL allows you to fetch only the fields you need, with no unnecessary overhead. This helps keep network responses small and fast.

However, GraphQL doesn’t automatically guarantee small responses. This is especially apparent when a field contains a list. To avoid enormous response from a seemingly small query, lists, containing unbounded maximum amount of items, use pagination:

query RoomStays($cursor: String = null) {
    reservations(first:10 after:$cursor) {
        edges {
            node {
                # reservation fields
            }
        }
        pageInfo {
            hasNextPage
            endCursor
        }
    }
}

Here, when no $cursor is provided, only the first 10 reservations are returned. To retrieve the next 10 reservations, the same query can be sent with $cursor set to value from endCursor field; and so on for the next 10 reservations. When there are no more results, hasNextPage will be set to false.

While the example uses reservations, it works the same for all connections.

The response to the previous example would look like this:

{
  "data": {
    "reservations": {
      "edges": [
        {"node": {...}},
        {"node": {...}},
        ... 8 more results       
      ],
      "pageInfo": {
        "hasNextPage": true,
        "endCursor": "bWFkZSB5b3UgbG9vaw=="
      }
    }
  }
}

Defaults¶

When no cursor arguments are provided, by default first:20 will be used, that is, only the first 20 items will be returned.

Unless otherwise specified on the field, maximum number of items a connection can return is 100.

Backward pagination¶

In addition to previously described forward pagination, 3RPMS also supports backwards pagination using last and before arguments, and startCursor and hasPreviousPage fields.

query RoomStays($cursor: String = null) {
    reservations(last:10 before:$cursor) {
        edges {
            node {
                # reservation fields
            }
        }
        pageInfo {
            hasPreviousPage
            startCursor
        }
    }
}

Here the last 10 reservations are returned. Similarly to before, to retrieve the previous 10 reservations, same query can be sent with $cursor set to value from $startCursor. When there are no previous reservations, hasPreviousPage will be false

Reference¶

Types prefixed with * are conventions and do not represent actual implementations. can think of them like virtual-interfaces. Use graphql introspection to see the real type implementations.

*Connection¶

Arguments¶

Argument	Type	Description
first	Int	Maximum number of items to return
after	String	takes the cursor type as described before
last	Int	Maximum number of items to return
after	String	takes the cursor type as described before

Forward pagination uses first and after fields. Backward pagination uses last and before fields. While both pagination types can be used together, its strongly discouraged, as it leads to difficult to understand results.

Fields¶

Field	Type	Description
edges	[*Edge!]	List of edges, containing edge-cursor and node
pageInfo	PageInfo!	Contains information about current page. Can be used to determine if more pages can be queried
totalCount	Int!	Total number of items in the connection, i.e., ignoring pagination

*Edge¶

Field	Type	Description
cursor	String!	Cursor representing edge’s location in the connection
node	*Node!	Items the connection wraps

Your integration likely is not going to need cursor field. startCursor and endCursor fields from PageInfo type should be used instead in most scenarios

PageInfo¶

Field	Type	Description
startCursor	String	Cursor corresponding to the first node in edges
endCursor	String	Cursor corresponding to the last node in edges
hasNextPage	Boolean!	Indicate whether more edges exist after last edge
hasPreviousPage	Boolean!	Indicate whether more edges exist prior to the first edge