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

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

This article is a guide to getting connected, performing your first few queries, and setting 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 work with, tooling is likely available to get you started quickly.

For this article, we'll use the Insomnia GUI client as a visual way to explore the API.

You're 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'll 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.

You'll likely want far more data than shown above, so the next step is to discover what's available.

We don't 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 isn't available, you may first need to click Refresh schema.

This opens a panel on the right containing a clickable schema browser.

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:

Alternatively, position the cursor on a new line in the data request and press CTRL+Space. This reveals a list of available fields to pick from.

Simple data types such as String, Boolean, and DateTime can be requested by adding the field name on a single line, as above.

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

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

We can continue to expand the data requested. This query also includes the user's course results, including detail about the related course.

By exploring available fields, complex data sets can be returned from a single request. Note that to maintain performance, nesting of related data is limited to three levels deep.

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

The pagination data is returned as a separate block, and several additional fields are available from the paginatorInfo item in the schema:

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

None of the queries performed so far have contained any arguments, but the schema browser shows 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's an example of the useful user_search argument, which filters on any match in the first name, last name, or email fields:

To explore the most powerful argument — filter — we'll move to a results query and request some course results. In this example, we want any course results 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 reflects the different query name and fields requested.

If you're 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.

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

We'll continue to add features, which will always be available via the schema browser.

You can read more about GraphQL technology here.