Getting started with the GraphQL API

The iHasco GraphQL API was released early in 2021 and powers our LMS reporting tools.

This API is now directly available to our clients using the same access tokens as our REST API. If you need to filter your data down by date range, names or custom field values then this API is for you.

This article is intended as a guide to get you connected, perform your first few queries and set you on a path to explore in detail how the GraphQL API can benefit your business.

GraphQL is supported by many programming languages and frameworks. Whichever language you wish to work with, it is likely tooling is available to get started quickly.

For the purposes of this article, we will use the Insomnia GUI client as a visual way to explore the API.

Setting up Insomnia

• Ensure you have some user and course result data in your LMS
• Create a new Request, change it’s Verb to POST and it’s body type to GraphQL
• Enter https://api.ihasco.co.uk/graphql as the URL
• Change Auth to Bearer Token, add your api token into the Token box and ensure the Enabled box is checked
• Ensure there is a "Content-Type" header of “application/json” (this should have happened automatically)
  
  
  

Your first request

You are now ready to make your first request. Let’s start with a very simple query to list users.

Copy and paste the above code into the body tab and click Send. You will see a list of users returned in the right pane.

Looking a little closer at what happened, we told the API to perform a users query, and we asked for four data fields to be returned.

Examining the API Schema

It is likely you will want far more data than shown above, so the next step is to discover what data is available.

We do not maintain detailed documentation for this API because GraphQL is self-documenting - if you have the tools to read it.

Insomnia provides a convenient Schema browser for this purpose. From the schema button, select Show Documentation. If this option is not available, you may first need to click Refresh schema.

This will open a panel on the right containing a clickable schema browser.

You will need to click through the list of queries, the type of output from the users query and finally the detail of the User  item.

This provides the full list of fields available. Try adding the created_at  and last_login fields to your data request, like so:

An alternative means to reveal the schema is to position the cursor on a new line in the data request and click CTRL+Space. This will reveal a list of available fields from which one can be picked.

Requesting more data from a query

Asking for simple data types such as String , Boolean  and DateTime  can be done by adding the field name on a single line as above.

The real power of GraphQL lies in it’s ability to request nested related data. Taking custom_fields as an example, the schema browser tells us that this returns a list of UserField items, each of which has its own fields. 

We can ask for this data by expanding our query. Here we ask for custom_fields, but only the label and value fields:

We can continue to expand on the data requested. This query will also include the user’s course results, including detail about the related course.

You can see that by exploring available fields, complex data sets can be returned from a single request. Please note that in order to maintain performance, nesting of related data is limited to three levels deep.

Pagination

Pagination is applied to all requests and information about it is available as a separate item in the schema. Here is an example of including pagination info for our simple user request:

You can see our pagination data returned as a separate block and that several additional fields are available from the paginatorInfo item in the schema:

Adjusting which page is returned is done via a query argument which is explained below.

Query arguments and filtering

None of the queries performed so far have contained any arguments, but we can see in the schema browser that several are available.

Arguments are defined inside parentheses immediately following the query name. Requesting page two of the previous results would look like this:

You can apply multiple arguments either comma separated or split over multiple lines. Here is an example of the useful user_search argument which filters on any match in first name, last name or email fields:

To explore the most powerful argument - filter, we will move to a results query and request some course results. In this example, we want any course results that were completed after a certain date. This can be useful for daily updates to a separate application.

The response follows the same format as the user query, but reflecting the different query name and fields requested.

If you are familiar with database queries, you may recognise the way the filter is constructed. There are various operators and fields available, all listed in the schema browser:

Filters can also be nested to give even more control. As a final example, we’ll fully load the query arguments. Here we filter on multiple clauses (all of which must match) and also specify completed results only, just one course, pagination and a particular sort order.

Next steps

We hope the examples above give a taste of the ways this API can be used.

We will continue to add features which will always be available via the Schema browser.

You can read more about GraphQL technology here.