/
GraphQL documentation authoring best practices

GraphQL documentation authoring best practices

Here we have provided best-practice guidelines on how to write API documentation. While these recommendations are mostly aimed at Totara developers writing core APIs, following these guidelines will make any third-party services consistent with the rest of the platform.

For more technical information on how to actually implement the documentation in code, see Extending API documentation.

Style

For Totara developers, use a writing style that is consistent with Totara's internal style guide.

Write schema documentation for the intended audience of a third-party developer integrating with a Totara instance, not the Totara administrator.

When the in-product term for a feature or object is different from its name in source code, use the in-product term. For example, "audience" not "cohort".

Document all aspects of the API schema

Provide complete documentation on all parts of the schema including:

  • Queries and their arguments
  • Mutations and their arguments
  • Input and object types
  • Each individual field within an object, including their arguments
  • Enums and their values
  • Scalars
  • Interfaces
  • Unions

Reference type descriptions

Use of reference types is encouraged to provide flexibility to the API user. When defining reference types, keep the following in mind.

The description should describe which combination of fields are required to uniquely identify an object of that type. For example:

You must provide either an id or both instancetype and instanceid to uniquely identify a single record.

It should also also describe any additional filtering that might be applied when identifying the object. For example, the core_user_user_reference type excludes deleted users and users from other tenants if the requesting user is a tenant member. This is important information that will impact the behaviour of the reference type, so should be called out in the type description.

Default values

In some cases you might specify the default value for an input property in the schema, but in other cases it is preferable to make the input pro