All requests to the external API are made through a single endpoint:

https://YOUR-SITE-URL/api/graphql.php

Requests are made via the HTTP POST method with a JSON-encoded body:

$ curl 'https://YOUR-SITE-URL/api/graphql.php' \
    -X POST \
    -H 'Authorization: Bearer YOUR-API-BEARER-TOKEN' \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    --data-binary '{ "query": "query { totara_webapi_status { status } }", "variables": "{}" }'

See the Authentication section below for how to obtain a valid Bearer token.

The expected response for this request would be the following JSON object:

{
  "data": {
    "totara_webapi_status": {
      "status": "ok"
    }
  }
}

The external API uses OAuth 2.0 via the client credentials grant type to authenticate requests. This involves three steps as outlined below.

1. Register a client

To register a client, log in to your Totara site and navigate to 'API Clients'.

Click the Add client button and provide information to describe the purpose of your client.

Make a note of the client id and secret for step 2.

2. Request a token

To programmatically request a token, call the OAuth 2.0 token endpoint as follows, passing the client_id and client_secret obtained during step 1:

curl -X POST 'https://YOUR-SITE-URL/totara/oauth2/token.php' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=client_credentials&client_id=CLIENT_ID_HERE&client_secret=CLIENT_SECRET_HERE'

The response will be:

{
  "token_type": "Bearer",
  "expires_in": 3600,
  "access_token": "YOUR-API-BEARER-TOKEN"
}

3. Submit a request with a valid token

Copy the value from the "access_token" property in the response into the 'Authorization: Bearer' header of your request.

A simple GraphQL request might look like this:

query my_query {
  totara_webapi_status {
    status
  }
}

This request consists of the following.

The query keyword

This indicates this is a read-only request. 'mutation' is used for requests which write data. The keyword is optional, but when provided the specific actions within the request must match the keyword given.

Request name (my_query)

Optional string to allow the request author to describe the purpose of the request. It is not used by the server.

Query or mutation name (totara_webapi_status)

Within the outer curly braces you must specify at least one query or mutation to execute (typically just one but requesting multiple is allowed).

The available queries and mutations are specified in the reference documentation.

Response structure

In GraphQL it is up to the query author to specify the data they want to receive in the response.

The curly braces and field names within them specify the data structure. They must match the structure of the type that is returned by that query or mutation.

Types can be complex (contain properties that represent other types), so additional curly braces are used to obtain properties of subresources in one request. For example, to get a list of course names and the name of each course's category:

query get_courses {
  get_courses {
    fullname
    category {
      name
    }
  }
}

Arguments and variables

Some queries and mutations have optional or required arguments which require additional data to be passed with the request.

User-provided data is kept separate from the body of the request as variables. Variables are passed as a separate JSON object with the query. To make use of variables, the structure of the query changes slightly:

Query

query get_course($courseid: core_id!) {
  core_course(courseid: $courseid) {
    fullname
  }
}

Variables

{
  "courseid": 2
}

In this example the ‘core_course’ query has an argument 'courseid'. It must be of the type 'core_id' and it is required (the ! suffix is used when a field must be provided). Available arguments are listed in the reference documentation for a query or mutation. Although values can also be hardcoded in the query, it is good practice to use variables to support argument validation and query reuse.

Variables are represented by strings starting with the dollar sign ($). Any $variable specified within the body of the request must be defined in the round brackets after the outer query name. When defining a variable you must specify its type. Variables will be validated according to their type before query execution. Complex types (types with properties made of other types) are allowed but must be defined in the schema.

The variables object that is passed with the request must have keys that match the variable names and give values that are compatible with the specified type for that variable.

Field arguments

Like queries and mutations, fields can support arguments. For example, here the argument on the timestamp field determines how the field is formatted in the response:

query test {
 totara_webapi_status {
   status
   timestamp(format: DATETIMELONG)
  }
}

Aliases

You can prefix a query, mutation or field with a different name and the server will return it as the key you specify. This can be used to return data to match a certain structure, or to differentiate if you are requesting the same field multiple times.

query test {
  my_query_name: totara_webapi_status {
    status
    long_year: timestamp(format: DATETIMELONG)
    short_year: timestamp(format: DATETIMESHORT)
  }
}

would return:

{
  "data": {
    "my_query_name": {
      "status": "ok",
      "long_year": "27/05/2022, 10:51",
      "short_year": "27/05/22, 10:51"
    }
  }
}

For more information on the GraphQL language see this Introduction to GraphQL.

You can perform introspection against the external API directly.

Alternatively, you can download the current external API schema for your site here: https://YOUR-SITE-URL/totara/api/documentation/schema.php