GraphQL - Connections and Paging
Query Root Level Connections
Each Xurrent account contains numerous lists of records: requests, organizations, people… In the specialist user interface you will typicaly view these lists via the Records console.
In GraphQL lists of records are called Connections. This might sound strange: why not name these collections of items just ‘Lists’ ? Knowing that GraphQL was initially developed by Facebook (before being publicly released in 2015), one immediately understands that in the context of social networking it was a logical choice to call these lists ‘Connections’ .
The main entry point for GraphQL queries are called Root Level Connections. In the Xurrent GraphQL API the available Root Level Connections are listed here.
Let’s have a look at the Root Level Connection for requests. This Root Level Connection is defined as:
requests (RequestConnection!)
This means that the requests object is of object type RequestConnection. You know from the previous chapter that the ending exclamation mark means that Xurrent GraphQL will allways return a value. Check here the fields that are available for a RequestConnection.
Exercise:
Create a GraphQL query to get the the number of requests in the Widget Data Center (id = wdc) account.
Make sure you specify wdc in the header info and to include the record type Request to the scope of the personal access token.
This is how the GraphQL query looks like in Insomnia: .
Connections and Pagination
Probably you are not just interested in the number of requests in the Widget Data Center account but in the details of some requests in the list. This list can be retrieved with the nodes field. Nodes is defined as:
nodes ([Request])
The square brackets indicate that this field will return a list of objects of type Request. The problem with a list is that it can consist of millions of records. Connections allow lists of records to be accessed using pagination. The Xurrent GraphQL API allows you to retrieve one page at a time and one page can contain a maximum of 100 records. When retrieving a Connection you need to specify either with a first or last argument the upper limit on the number of records to be returned (retrieve the first x number of records or the last x number of records from the Connection).
You can specify these paging details as an argument to a Collection. In GraphQL, arguments are specified in parentheses after the field and before the Selection Set.
In the example hereunder, the GraphQL query will get the first 5 requests from the RequestConnection and for each of these requests the subject is returned.
Check now the other arguments that are available for paging through a RequestConnection here. With the after and before argument you can specifiy a so called cursor. With the cursor you specify the record (based on the node ID) in a Connection to give some context to the arguments first and last: (first:5) means the 5 first records starting from the cursor.
When your integration needs to browse through multiple pages in a Connection, you need to keep track of the actual cursor and you need to know if there are still any pages left.
The PageInfo object, which is a field of a Connection, contains all the answers to these questions: with the field endCursor you can skip to the next page and with hasNextPage you can check if there is a next page.
Let’s do some pagination now.
Exercise:
Create 2 GraphQL queries. In the first one you retrieve the first 3 requests in the Widget Data Center (id = wdc) account. For each request you ask for the requestId (the record ID as displayed in the UI), the subject and the name of the requestedFor person. Make sure you retrieve paging info : check if there is a next page and retrieve the endCursor. Copy the endCursor to retrieve the following 3 requests from this list.
This is how the first GraphQL query looks like in Insomnia:
And this is the second GraphQL query:
