API hooks

API hooks

API hooks are an extension mechanism by which a platform's API can be used to replace LTI functionality which it does not support. For example, if a platform does not support the Membership service then the an API hook can be registered to direct the library to code which implements the equivalent functionality using its API. In this way richer LTI integrations can be seamlessly built; the sender of a message will not be aware as to whether it is handled by an LTI connection or via a proprietary API.

This library currently supports the following API hooks:

• Parameter type:
  • User ID
  • Context ID
• Service type:
  • Outcomes service
  • Tool Settings service
  • Course Groups service
  • Membership service

The parameter type hooks are useful when an ID value other than the LTI value is needed to be used with the platform API. For example, the LTI user ID passed by Canvas cannot be used for making API requests; Canvas uses its own internal user ID value with its API. The User ID API hook, therefore, allows this internal user ID to be used as the LTI user ID to avoid this issue.

The library currently includes support for the following API hooks (follow the links for more details of each one):

Platform	Family code	API hooks
Moodle	moodle	Course Groups service Membership service
Canvas	canvas	User ID Course Groups service Membership service

These can be extended by writing your own code and registering the API hook (see below). Contributions of additional API hooks to include in this library are welcomed.

Using API hooks

The only change required by a system wanting to permit support for an API hook is to register it in advance of using the related functionality in the library. For example, to add support for the Membership service using the Moodle API, add the following line:

ResourceLink::registerApiHook(ApiHook::$MEMBERSHIPS_SERVICE_HOOK, 'moodle', 'ceLTIc\LTI\ApiHook\moodle\MoodleApiResourceLink');

This will mean that, if the Moodle instance does not offer the Membership service to the tool provider, the ResourceLink->getMemberhips() method will use the code contained in the ceLTIc\LTI\ApiHook\moodle\MoodleApiResourceLink class instead to complete the request. If the Context->getMemberships() method is required instead (or as well), then just register the Context-level API hook:

Context::registerApiHook(ApiHook::$MEMBERSHIPS_SERVICE_HOOK, 'moodle', 'ceLTIc\LTI\ApiHook\moodle\MoodleApiContext');

The family code parameter passed in an LTI message (e.g. moodle) is used by the library to determine the availability of an API hook. There is no limit to the number of API hooks which may be registered.

Priority of API hooks

A service type API hook will only be used if the equivalent functionality has not been made available by the platform. If you want the API hook to be called in preference to a standard LTI service implementation, then make sure that the platform does not offer the service.

Implementing a new API hook

The easiest way of determining how to implement an API hook for a new platform is to review the code for an existing one. The code should be added to a new class and the name of this class used when registering the API hook; for example:

ResourceLink::registerApiHook(ApiHook::$MEMBERSHIPS_SERVICE_HOOK, 'myvle', 'my\namespace\MyVleApiResourceLink');

The family code should match the value being passed by the platform; the class name can be of your own choosing - just make sure that the class is accessible either via the autoloader or by including the file(s) directly.