Developing for the External GraphQL API

Developing for the External GraphQL API is very similar to developing for other endpoints. See Developing GraphQL APIs for Totara and Implementing GraphQL services for more details.

The main differences are in the strictness of standards that we enforce for external services, and our deprecation policies.

Stricter implementation standards

• We require Totara developers to provide full documentation for all nodes within their external GraphQL schema. Don't assume knowledge of internal behaviour in API documentation. Do try to describe any factors that might impact use of the services - for example, global configuration settings that change API behaviour.
• External services must implement API service examples via metadata.json files. See Extending API documentation for details.
• External services should use reference input types rather than internal database ids.
• External services should implement enums rather than relying on magic numbers for input data (for example use the core_format enum instead of integer types).
• External services must implement all options that can be specified, or clearly document and return a clear error if some options are not supported (for example if you use core_format, ensure the service handles all the available formats correctly).

Deprecation policies

Internally we apply the same standards of deprecation to our internal and external GraphQL APIs, but in general we will be more strict with external APIs, so the bar is set higher for any exceptions to our deprecation policies. See Changes to the GraphQL APIs for more details on those.