GraphiQL Explorer

GraphiQL is a live, interactive GraphQL query editor so that you can inspect the schema, run queries and see API results easily.

When you first authenticate with an Altrata endpoint with GraphiQL, you will see that there are three sections. The navigation on the left is for the API documentation. There will be two sections, one for building out your query and then the section on the right is where your response data will be shown once you run your query.

If you click on the first item in the left hand navigation, you will open the "Docs" section.

The "Docs" section is where you can get a better understanding of the schema types. This will explain the data types you can expect to receive back if you add those properties to your query. In addition, it will give you information on what the properties mean.

For example, if we click into the "Organization" schema, you will see that it breaks down all of the properties that belong to it, the data types that all of the properties will return and what data the properties are returning.

To make it easier for you to build a query, the Explorer section in GraphiQL allows you to see each of the schemas/collections that you can query against.

All of these schemas/collections are available to be queried against. To make it easier to build a query, you have the ability to click on the schema that you want to query and it will auto populate in the query section for you. For example, if I click on the "personKeywordSearch", you will see that all properties that belong to that schema/collection are displayed, and you will see that the "personKeywordSearch" has also been added to the query builder:

On the Explorer, you will notice that the dropdown for PersonKeywordSearch has opened and there are now more items visible.

You will see that there are two different color types on the properties that are now visible. "filter", "searchKeyword" and "pageInfo" are in a different color to "items" and "pageInfoResponse". This is because the items that are in a turquoise color are items that you have the ability to query against, and the items that are in the normal blue color, are items that you can specify you want to be returned in your query.

Building on top of our 'personKeywordSearch" query that we started in the previous section, we can see that we can query against a searchKeyword filter and pageInfo. For this example, we will only look at the searchKeyword filter, pagination will be looked at in the next section.

If we click on the searchKeyword in the Explorer, it will then be added to the query builder.

We can see that the "searchKeyword" has been added to the query and it has an empty string that you will need to populate. We should now populate the empty string with a value:

You will see that the value we put into the searchKeyword in the query is also being displayed in the Explorer.

As you can see in the image above, the "personKeywordSearch" is now in red and showing an error. This is because we have entered a query but we have not provided which properties we want our query to return. To specify which properties we want our query to return, we can click on the items field in the Explorer, and then select a property.

We have selected the "items" field for our response but we are still seeing an error in the query builder. This is because the "items" field, has multiple properties that belong to it. If filed or property has children properties, then an error will be displayed in the query builder for that field, until you have specified a child property for it. To make the error go away, we need to select children properties.

As you can see in the image above, I have selected "id", "firstName", "lastName" properties, and the error on "items" has now gone because we have built a valid query.

Before we run the query, let's breakdown the query itself.

The first section of the query is building out the actual query itself. We are specifying what we want the query to be ran against.

The second part in the query that occurs in the second curly braces, is what we want to be returned in our results.

If we press the play button, our query will now run and we will be shown the results on the section on the right hand side.

In REST APIs, as the data structure is pre-deteremined, you will automatically get pagaination on your GET requests if the endpoint supports pagination. However, in GraphQL, as you need to specify everything that you will like returned - you will need to specify if you want paganiation results to be returned to you.

If we take our example from before, we can add pagination to it so that we can see the total amount of results that have been returned for the query, the amount of pages that have been returned and then the cursor information so we can access those pages.

As you can see from the image above, it has been specified that we would like page information to be returned. We would like the cursor information so that we can navigate between pages and we would also like the total results count to be returned. When we run this query, we then get back this information.

For our query, we can see that there is a total result count of 23. Our "startCursor" is returning null and our "hasPreviousPage" is returning false, because we are currently on the first page. We can see that "hasNextPage" is returning true because there is another page of results for us to look at. Lastly. we can see that "endCursor" is providing us with a string that we can use if we want to navigate to the next page of results.

Based on our results, if we wanted to go to the next page of results, we need to add "pageInfo" to our query. To do this we can click on "pageInfo" in our explorer which will automatically add it out our query with empty curly braces, or you can manually type it into the query.

In the "pageInfo" section of the query, you will need to specify what you would like to happen when you go to the next page. If you look in the explorer, you will see a number of properties you can put into the "pageInfo" object.

To navigate to the next page, we would need to add the "after" property to our "pageInfo" object and specify the page

When we run the query now, we will be taken to the next page. We can see that we are on the next page, as we are told the next page cursor and also the previous page cursor. The previous page cursor is displayed in the "startCursor" property. If we wanted to return to the previous page, we would change the value of our "after" query to contain "ALTPTR0".

As well as being able to move between pages, you will also be able to limit the results you get returned back to you in a page. To do this you can utilise the "First" and "Last" properties.

By default, we will return a total of ten items in the list. However, you are able to specify a higher amount if you wish. From our query above, we know that there is a total of 23 results, rather than looping through all of the pages to see the results, we could utilise the 'First' property, to return all 23 items. To do this, we need to add it to our 'pageInfo' object and specify the number.

If we look at our results, we will see that there are no next page or previous page as all results are loaded onto the first page.



You can also pair the "first" and "last" functionality with the page cursor to limit the amount of results that are displayed per page:

If we run this query, you will see that the results are limited to four and to get the next four results, we would need to enter the next page cursor.



As GraphQL utilises a singular endpoint rather than having multiple, it allows you to have multiple queries within one HTTP call. This allows you to reduce the amount of HTTP calls you will need to make to get the data that you want.

To have multiple queries in one call, all you will need to do is append a second query into the query you are building.

In the image above, you can see that the first query is searching in the personKeywordSearch field and then when the first "items" sub-field is closed in the "personKeywordSearch" field, we add a second query that will search in the organizationKeywordSearch field. Both queries are still contained within the "MyQuery".

Once the query has been ran, you will see that you will be returned the search results from both queries.

For every query that you run in GraphiQL, it will added to the saved query section. To see this, you will need to press the second icon in the left hand navigation.

All of your queries will be saved here. You will have the ability to rename them by pressing the pencil icon. You can favourite the query to ensure that it does not get lost and you can also press the last icon to remove the query from your history.

When building your query, you can give it any name that you like. By default, it will be titled "MyQuery", but this can be changed to be what ever you want.