...

GraphQL - What is it?

Concepts

Please read our beginners guide for a quick overview of GraphQL's core concepts: /wiki/spaces/~712020ed0261f15a044ee387ddaa27aaf37f0d/pages/840728681.

Schema types

In Totara we separate our schemas based on their use-case. The queries, mutations, types, and so on we define in one schema type has rules about whether it’s available in another. At Totara we have three schema types (use cases) - these are external, internal, and mobile.

External

The external schema type is where the schema for our external APIs is written. This is a special schema type as the external schema is accessible by other schemas. In this way, it can thought of as the “root” schema.

The external schema is any schema file placed under the plugin's webapi/ directory. For example, in the local_todo plugin, the external schema file would have a file path of server/local/todo/webapi/schema.graphqls.

Internal

The internal schema type is where the schema for our internal client is written. The internal schema is also called ajax in the codebase. The internal schema is not shared to another schema and is only available when using the internal schema.

The internal schema is any schema file placed under the plugin’s webapi/ajax/ directory. For example, in the local_todo plugin, the internal schema file would have a file path of server/local/todo/webapi/ajax/schema.graphqls.

Please see Developing for the AJAX GraphQL API for more information, or check out our quick-start guide on creating an internal query in this document.

Mobile

The mobile schema type is where the schema for our mobile API is written. The mobile schema is used by our mobile app. This guide doesn’t cover the mobile API at this time.

The mobile schema is any schema file placed under the plugin’s webapi/mobile/ directory. For example, in the local_todo plugin, the mobile schema file would have a file path of server/local/todo/webapi/mobile/schema.graphqls.

Quickstart - Create an Internal Query

Internal query - what’s that? Internal queries are our

Create the schema

• Create a webapi directory in your plugin rootdirectory. For example, for my local_todo plugin, this would be in /server/local/todo/.

• Under the webapi create a ajax directory

• Create a schema.graphqls file under the ajax directory

• In schema.graphqls let’s define the todo_item type by adding the following:

  • Code Block
    language graphql
    type local_todo_item { id: core_id title: String completed_at: core_date }

  • This adds a new type with id, title and completed_at which we will have access to when using this type.

...

• Create the persisted query file in the webapi/ajax/items.graphql with the following:

  • Code Block
    language graphql
    query local_todo_items { local_todo_items { items { id title completed_at } } }

Create the backend

Now we need to create the PHP backend to handle the query.

...

• 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