This is early phases of a quickstart guide for creating GraphQL APIs in Totara.
Mostly this is just notes at this point
Examples given is of a plugin named local_todo
which is the plugin todo
in the local
directory.
GraphQL - What is it?
Please read our beginners guide for a quick overview of GraphQL's core concepts: /wiki/spaces/~712020ed0261f15a044ee387ddaa27aaf37f0d/pages/840728681.
Quickstart - Create an Internal Query
Create the schema
Create a
webapi
directory in your plugin rootUnder the
webapi
create aajax
directoryCreate a
schema.graphqls
file under theajax
directoryIn
schema.graphqls
let’s define thetodo_item
type by adding the following:type local_todo_item { id: core_id title: String completed_at: core_date }
This adds a new type with
id
,title
andcompleted_at
which we will have access to when using this type.
Create the query
We’ll start off our APIs with creating a query to retrieve a list of the type todo_item
.
In
schema.graphqls
define the result we’ll get back from the query by defining the following type:type local_todo_items_result { items: [local_todo_item!]! }
Notice here we’ve used
!
in two places. This indicates the field is non-nullable. We’ve used this here to say that we always expect an array, by putting the exclamation mark on the outside of the array[...]!
. We also used to to say that the elements of the array cannot be null[my_type!]
.
Now we have the result defined, let’s define the query. We do this by extending the type
Query
and adding our query into it. Let’s do this:extend type Query { local_todo_items: local_todo_items_result! }
This defines that the query
local_todo_items
should return thelocal_todo_items_result
type we defined earlier
Creating the persisted query
The persisted query is a definition of the query for the frontend component to import. We name this file the query name, minus the component name of the plugin we’re working with.
Persisted queries use .graphql
instead of the .graphqls
we used previously for the schema file.
Create the persisted query file in the
webapi/ajax/items.graphql
with the following:query local_todo_items { items { id title completed_at } }
Create the backend
Now we need to create the PHP backend to handle the query.
First we’ll create the directory for the query resolver by creating the following directory
/server/local/todo/classes/webapi/resolver/query
Now let’s create the query resolver class,
items.php
in the directory we just created.<?php namespace local_todo\webapi\resolver\query; use core\webapi\execution_context; use core\webapi\query_resolver; use local_todo\entity\item; class items extends query_resolver { /** * @inheritDoc * @throws \coding_exception */ public static function resolve(array $args, execution_context $ec) { global $USER; $items = item::repository() ->where('user_id', $USER->id) ->order_by('id') ->get(); return ['items' => $items]; } }
In this file we’ve defined the query resolve and we’re using the ORM of local_todo to return a list of items.
Now we create the type resolver directory
/server/local/todo/classes/webapi/resolver/type/
and the type resolver for itemitem.php
in the directory.<?php namespace local_todo\webapi\resolver\type; use core\webapi\execution_context; use core\webapi\type_resolver; class item extends type_resolver { /** * @param string $field - The field being requested * @param $source - In the case, source will be our `item` entity class as it's what's returned from the query resolver * @param array $args * @param execution_context $ec * @return mixed|void */ public static function resolve(string $field, $source, array $args, execution_context $ec) { return $source->$field; } }
Testing Queries
Testing Mutations
TODO:
Screenshots of how to set up the dev_graphql_executor
Maybe update the main doc for this
Add how to test generally - the below is not enough, need proper guidance
Tidy up steps - they can be much cleaner
👋 Say hello to whoever made it this far and is now just nosey 😂
To test this - Using the developer GraphQL API