Interacting with sessions

Owned by Michael Ivanov (Deactivated)
Sept 22, 2023
2 min read

When working with GraphQL APIs, it's important to understand how sessions are handled, as they play a crucial role in certain API types. This developer documentation provides guidelines on how developers should interact with sessions when extending Totara GraphQL APIs.

Types of Totara GraphQL APIs and their interaction with sessions

Totara GraphQL APIs can be broadly categorised into the following types with respect to sessions:

  1. Ajax API: This type of API utilises sessions to manage user interactions with the Totara website. Ajax API requests often involve user-specific data and require session management to maintain state.

  2. Mobile API: The Mobile API is designed to support Totara's mobile app. It also uses sessions, primarily for backward compatibility with the existing code.

  3. External API: Unlike the Ajax and Mobile APIs, the External API does not rely on sessions. It serves as a stateless API for external integrations and does not use sessions to store user-specific data.

Changes in Totara 18

With the release of Totara 18, a significant change was made to how sessions are handled within GraphQL queries. This change primarily impacts the Ajax API.

Previously, in Totara 17 and earlier versions, sessions remained open for writing throughout the execution of GraphQL queries. This allowed developers to modify sessions directly within GraphQL queries. However, in Totara 18, an optimisation has been implemented to improve the performance of concurrent GraphQL queries. As a result of this change:

  • Sessions for writing are automatically closed before the query resolves

  • Modifying website sessions directly within GraphQL queries will result in the totara_webapi\exception\reopen_session_for_writing_exception exception being thrown

Action required for Ajax API developers

To retain the ability to write to sessions within GraphQL queries in T18, Ajax API developers should follow these steps:

  1. Add the core\webapi\middleware\reopen_session_for_writing middleware to the GraphQL query.

  2. Ensure that the core\webapi\middleware\reopen_session_for_writing middleware is positioned as the topmost middleware in the list of middleware used in the query. This way if any following middleware modifies the session the changes won’t be lost.

Disabling optimisation

For developers who require the previous behaviour of keeping sessions open for writing within GraphQL queries, it is possible to disable this optimisation. This can be achieved by setting the configuration variable $CFG->graphqlsessionwritecloseenabled to false in the config.php file. Please note that disabling the optimisation will negatively impact the performance of pages where multiple GraphQL requests are executed simultaneously.

Mobile API unaffected

It's important to note that the Mobile API is not affected by the change introduced in Totara 18. The Mobile API already closes sessions for writing before query resolution, ensuring compatibility with the updated session-handling mechanism.