GraphiQL Explorer

graphiql is a live, interactive graphql query editor so that you can inspect the schema, run queries and see api results easily the examples below will be utilising our profile api, which you may or may not have access to depending on your subscription package however, the explanations provided will still be applicable to all endpoints 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 schema 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 explorer 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 a 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 pagination 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 navigate to the next page 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 after fetches items after the specified cursor example after cursor2, return all items on that page before fetches items before the specified cursor example before cursor2, return the first 20 items this will return items 20 items before page 2 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" limiting results 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 first fetches the fist 'n' elements in the list example only return the first 10 items last fetches the last 'n' elements in the list example return the last 3 items of the results on a particular page 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 multiple queries 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 saved 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