This page is focused on access to the external GraphQL API. See the documentation on other endpoints for information on how to access different endpoints.
In order to interact with the external GraphQL API you might choose to use a GraphQL client rather than making direct HTTP requests. There are many different clients available as independent software, or as extensions to existing browsers or IDEs. Below we describe a few common clients and how they are configured to access Totara's GraphQL APIs.
In all cases, you will need three pieces of information: your site URL, and a valid client ID and client secret. See the user documentation for how to create a client with an id and secret.
There are a few ways to use Postman, but our recommendation would be to create a collection for your Totara API requests.
An example collection that you can import into Postman to use as a starting point can be found here:
To execute the HTTP request to get a new token, click Run all requests in file. You should get results in the window below like this:
You can then copy the access token and follow the steps below.
GraphQL integration within PHPStorm is achieved via the JS GraphSQL plugin. Install this plugin via Preferences > Plugins:
PHPStorm GraphQL access is configured by a new file in the project's root folder. Create a file called .graphqlconfig in the top-level root folder (the one that contains server and client directories).
If your site is publicly accessible you should prevent downloads of the .graphqlconfig file in your web server configuration. That is because this file (which we will create next) will contain secret information that could be used to make API requests.
The format for the .graphqlconfig file for external API access is:
Once the .graphqlconfig file has been created, open the GraphQL tab and add a new schema configuration:
Specify the folder that contains the .graphqlconfig file:
You should end up with a new endpoint and some information about the schema (types, interfaces, etc.).
You can use the GraphQL plugin in a number of ways:
Open any .graphql or .graphqls file and get auto-completion and syntax highlighting based on the API schema
Execute .graphql files, including support for passing variables and easily browsing the results
Execute arbitrary queries via new .graphql files or scratch files
The play icon allows you to execute a query against the specified endpoint. The V icon allows you to provide a JSON structure containing variables that will be used as query arguments. Results will appear in the panel below:
Altair is a GraphQL client available on multiple platforms, including as a Google Chrome extension in the Chrome store.
After installing the Chrome plugin, an extension icon will appear next to the URL bar:
Clicking it will open the client:
To use the client:
Obtain a valid access token. You can do this via a command line cURL request.
Put the following POST request into the Send request bar at the top: https://YOUR-SITE-URL/api/graphql.php
Open the Headers dialog via the icon on the left and create an Authorization header with the value: Bearer YOUR-BEARER-TOKEN
To test queries are working you can enter the following query: