Developing GraphQL APIs for Totara

This page provides detailed background information on how our GraphQL APIs are organised. If you want to implement a GraphQL service, you might be more interested in the Implementing GraphQL services page.

For more background on the structure and format of GraphQL requests, see Using GraphQL APIs.

Endpoint types

We offer a number of different GraphQL APIs, each with its own separate endpoint (URL) where it can be accessed. You can find out more about the differences between these APIs on the Available APIs page.

Each endpoint has its own schema, defined via schema files, which means different services are available in different endpoints.

About schema files

Our implementation of GraphQL uses schema files written in SDL to define the API services that are available. Individual schema files (which are created within components and plugins) are combined by our schema loader into a single schema per endpoint type.

The naming of the objects within the schema must follow a specific convention, and the name that is used will determine the location in the server codebase where the specific object will be handled. See the Locations for files relating to services section below for details.

Building the schema

In order to allow plugins to specify their own schema in an extensible way, the overall schema for an endpoint is built from individual files located across the codebase. Schema building happens dynamically in code when required, but is cached as it can be a time-consuming operation to generate.

There are a few ways for a developer to access the full schema for a specific endpoint type:

Via introspection

Often it is not necessary to download the schema directly, as GraphQL clients can request details on the schema structure via an introspection query to the endpoint itself. In this case, the endpoint will build the schema if necessary and serve the result directly. Note that this is only available for the developer API and the external API when the enable_introspection admin setting is enabled.

Via a schema URL

When the development API is enabled, the full schema can be downloaded via the following URL:

https://YOUR-SITE-URL/totara/webapi/dev_graphql_schema.php

When the external API is enabled, the external schema can be downloaded by a logged-in user with access to the API reference documentation via:

https://YOUR-SITE-URL/totara/api/documentation/schema.php

Build via CLI

There is a command line (CLI) PHP script within the codebase, which can be run to generate schema for a specific endpoint:

Produces a complete GraphQL schema for the specified type by concatenating individual schema files. The specified file will be overwritten if it already exists.

php ./server/totara/api/cli/generate_external_schema.php -t=ajax -f=totara.graphqls

Options:
-h, --help            Print out this help
-t, --type            Endpoint type e.g. 'ajax', 'dev', 'mobile' or 'external' (default)
-f, --file            Writes the schema to the given file. Use '-' for stdout

Build via API reference docs build script

There is another command line (CLI) PHP script which builds the files needed to generate the API reference documentation. This will generate schema files for all endpoint types along with the required metadata.json files, via the command:

php server/totara/api/cli/prep_api_docs.php

See the Extending API documentation page for more details on how to build the reference documentation.

Locations for files relating to services

The naming of a GraphQL file uses a consistent naming convention, which determines where the code that is executed is stored in the server codebase:

[1]  {$component_name} is the 'frankenstyle' name made up of the component type plus component name, e.g. 'mod_perform' or 'block_current_learning'. This maps to a specific {$component_path} for the plugin as determined by core_component::get_component_directory().

[2] Persisted queries belong to a specific endpoint type (currently either 'ajax' or 'mobile' as these are the endpoint types that support persisted queries). The endpoint the request is made against will determine which path is requested for the persisted query.

[3] Schema files in the root of the webapi/ directory are included in all endpoints, whereas schema files in a named subdirectory are only included in that endpoint type's schema.

Examples

An AJAX request for the persisted query with the operation name 'mod_perform_add_participants' would be found on the server at 'server/mod_perform/webapi/ajax/add_participants.graphql'.

The resolver for the core_user type would be defined in the class file found on the server at 'server/lib/classes/webapi/resolver/type/user.php' with the fully-qualified classname of '\core\webapi\resolver\type\user'.

The resolver for the mutation 'totara_api_delete_client' would be found on the server at 'server/totara/api/classes/webapi/resolver/mutation/delete_client.php' with the fully-qualified classname of '\totara_api\webapi\resolver\mutation\delete_client'.

Totara's use of GraphQL

Our implementation

Our server-side implementation of GraphQL makes use of the graphql-php library. See their documentation for more information about the library itself.

The library itself is included as a dependency to our 'required' package, with package code stored in libraries/required/webonyx/graphql-php.

Our implementation of the library can be found in the code folder server/totara/webapi/. Our implementation provides the API endpoints and some Totara-specific wrappers of the library's code.

Some important files within this component are described below:

In addition to the server/totara/webapi/ folder, the implementation of some of the core features are in server/lib/classes/webapi. For example:

The lib folder also contains core implementations of some of the features of the API, such as middleware, formatters and resolvers.

Request processing order

A typical successful request will take the following path through the code:

1. Endpoint file called (e.g. /api/graphql.php for external API).
2. Control passed to endpoint api_controller (see server/totara/api/classes/controllers/) process() method.
3. action_graphql_request() method called on api_controller.
4. A new webapi server (server/totara/webapi/classes/server.php) is instantiated and handle_request() method is called.
5. A new webapi processor (server/totara/webapi/classes/processor.php) is instantiated and process_request() method is called.
6. A new StandardServer (class from the php-graphql library) is instantiated and executeRequest() method is called.
7. Various asynchronous php-graphql methods are executed to manage the request.
8. Eventually control is passed to default_resolver (server/totara/webapi/classes/default_resolver.php) to identify the class to resolve the current part of the request.
9. The default_resolver __invoke() method identifies the resolver classname (via the GraphQL operation name) and calls the resolve() method on that class (also adding in any required middleware).
10. The resolve() method returns the required data, which is combined with data from other resolve() calls to build the complete response.
11. The response is constructed and returned to the user.