Changes to the GraphQL APIs

Owned by Liam Tanner
Last updated: Jul 28, 2023
3 min read

Our goal with our APIs is to provide a consistent, dependable interface that will not arbitrarily change and break code that depends on it. That said, over time it is necessary for APIs to evolve with the product, extending existing functionality, adding new functionality, and removing legacy functionality.

This page contains information about our change management policies for APIs, so you can know what to expect and how to track and identify API changes when upgrading your sites.

For technical information on how we deprecate code, see the GraphQL API deprecation process page. For broader information on how we handle deprecation in Totara beyond just APIs, see our Deprecation guidelines.

Information on API changes

We include detailed information on changes to our API in our product release notes. Developers can also find detailed information on changes in the codebase, inside files named upgrade.txt that sit inside specific component/plugin folders.

API versioning

We do not use separate API version numbers for our GraphQL APIs; versioning behaviour is tied to the major version of the underlying Totara version. 

Breaking vs non-breaking changes

We identify a specific schema change as either a breaking or non-breaking change, depending on the impact it would have on existing usage of the API. A breaking change is one where code that calls the API would need to be updated to deal with a modification in the APIs behaviour.

Examples of breaking changes include:

  • Deleting an existing type, mutation, query, argument, field or enum
  • Adding a new required argument to an existing query or mutation
  • Changing the default value of an optional argument
  • Changing the type of an existing field or return value
  • Making an optional field or argument required

A non-breaking change is a change where the impact on existing usage of the API is expected to be minimal, usually because the change represents an addition to the API that is likely to be ignored by pre-existing code. Examples of non-breaking changes include:

  • Adding a new query, mutation, type or enum
  • Adding a new optional argument to an existing query or mutation without changing the order of existing arguments
  • Adding a new value to an existing enum

Policy on making API changes

We define a set of rules on what changes are allowed, both in minor (point) releases and separately in major releases.

This policy applies to the AJAX and external APIs for Totara TXP, and the external API for Totara Cloud. It doesn't apply to the Ajax API for Totara Cloud, as we can introduce breaking changes to this API because it is not used by third-party plugins.

Minor release policy

  • We will not make breaking changes to an API in minor releases, unless:
    • The feature is explicitly marked as 'beta' or 'experimental', indicating it is not yet fully production ready and therefore subject to modification
    • In exceptional circumstances when required to fix a bug in the stable branch
  • We will not deprecate API functionality in minor releases, unless:
    • The feature is explicitly marked as 'beta' or 'experimental', indicating it is not yet fully production ready and therefore subject to modification
    • In exceptional circumstances when required to fix a bug in the stable branch
  • We may make non-breaking changes to APIs in minor releases
  • We will document all API changes (breaking and non-breaking) in minor release changelogs

Major release policy

  • We may make non-breaking changes in major releases
  • We may deprecate API functionality in major releases, in order to indicate that the functionality will not be available in the next major release
  • We may make breaking changes in major releases, so long as that functionality has been marked as deprecated in the previous major version
  • We may remove functionality in major releases, so long as that functionality has been marked as deprecated in the previous major version
  • We will document all changes (breaking and non-breaking) to the External and Mobile APIs since the previous major release in the release notes
  • We will only document breaking changes to the AJAX APIs in the release notes

Tooling to support tracking API changes

GraphQL uses a strongly typed, declared schema as the primary interface for the API. Therefore most changes that occur are represented by changes to the overall API schema.

Totara 17 ships with a schema diff tool that will output information about breaking and non-breaking changes between two schemas. We use this internally in our unit tests to enforce the above policies, and also to generate information about schema changes for our changelogs.

See the file:

server/totara/webapi/classes/tool/schema_diff.php

for more information.

We also keep a copy of the release schema within the codebase, which is updated as part of the release process:

server/totara/webapi/tests/fixtures/schema_diff/previous_release.graphqls

This can be used in conjunction with the schema diff tool and the current schema to identify any differences due to customisations.