External services description

Moodle 2.0

Purpose

This document explain how we describe and where we store the web service functions into Moodle 2.0.
We store service and function descriptions in the DB folder into a services.php file.
Web services functions will be located into servicelib.php files.
Descriptions will be parse by a service discovery function that will fill the database (extend the current discovery functionalities looking parsing the DB folders).

Administration pages

Moodle administrators will be able to manage services . By default all services will be disabled.

List of administration functionalities:

• enable a service (all the functions into this service will be available)
• associate a web service user (the user has web service capability) to some services => a user can only call a service that he is associated with
• create a custom service (add and remove functions from this service)
• search easily function by component in order to create a custom service

Administrators will also be able to create a custom service, selecting any existing functions.

external_functions table

List of web service functions.

Field	Type	Default	Description
id	int(10)	auto-incrementing
component	varchar(100)		Component where function defined, needed for automatic updates.
name	varchar(150)		function name: get_users, create_users,...
phpfile	varchar(255)		location where function defined - Needed for identifying
contextrestriction	int(1)		extra information - some functions may support context restrictions
requireslogin	int(1)		extra information - some external functions may not require $USER
requiredcapabilities	varchar(255)		capability ids (separate by comma)

Note about Petr Proposal:

• I don't think we need to insert a params description row as we have the params description into the description array.
• I removed requiredlogin because it can be inserted into the description array. The administrator should never change it.

New function: validate_context_restriction($currentcontext)

Each functions that supports restrictions must:

1. find out context of request from function parameters - when enrolling user to course it is a course context, when add post to chat it is chat context, etc.
2. call validate_context_restriction($currentcontext) - Moodle verifies $currentcontext is equal or child of restriction context, if not exception is thrown and script terminates.

The restriction context is stored in some global variable which is initialized in lib/setup.php using data from token tables.

external_services table

Service is defined as a group of web service functions.

Field	Type	Default	Description
id	int(10)	auto-incrementing
name	varchar(150)		Name of service (gradeexport_xml_export, mod_chat_export) - appears on the admin page
enabled	int(1)	0	service enabled, for security reasons some services may be disabled - The only editable field by the admin
custom	int(1)	0	Custom local service, created manually by admin or some other way (CAN BE updated automatically during the cron job => function not existing get removed). This field is useful if we want to implement an admin page where the admin selects some functions from a list of all external functions. Note: we probably need a button to desactivate all services in once.
customname	varchar(150)		As a custom service name cannot be found into lang files, we need a field for that

Note about Petr's Proposal:

• I removed the version row. If we want to create a special version number for a service, we could probably write it in the description array (it's not going to be changed by a Moodle administrator, it doesn't need to be saved into the database). Otherwise we could also use the moodle version to have some kind of reference about a Web Service API version.
• I removed requiredCapability, it should be an array into the description (same for function capabilities)
• custom row can now be updated during Moodle upgrade.

external_services_functions table

Specifies functions used by services.

Field	Type	Default	Description
id	int(10)	auto-incrementing
externalserviceid	int(10)		foreign key, reference external_services.id
externalfunctionid	int(10)		foreign key, reference external_functions.id
enabled	int(1)	0	function enabled, function might be disabled for security reasons - The only field editable by administrator ! This field has to be here cause a function can be enabled for the default core service but not enabled into a custom service

external_services_users table

Specifies services used by users.

Field	Type	Default	Description
id	int(10)	auto-incrementing
externalserviceid	int(10)		foreign key, reference external_services.id
userid	int(10)		foreign key, reference user.id

PHP array description

why a web service description

• in order to generate the WSDL for SOAP
• in order to generate documentation for protocol as REST or XMLRPC
• in order to clean automatically the params

code template

$object = new object(); $object->property1 = PARAM_NUMBER; $object->property2 = PARAM_ALPHA;

$params = new object(); $params->objects = array($object); $params->object = $object; $params->primarytype = PARAM_ALPHANUM;

$return = new object(); $return->values = array(PARAM_NUMBER); $return->value = PARAM_NUMBER;

$this->descriptions['function_name'] = array(

                                      'service' => 'service_name',
                                      'requiredlogin' => 0,
                                      'params' => $params,
                                      'optionalinformation' => 'Human readable text: "object" and "primarytype" parameters are optionals',
                                      'return' => $return );

Way to fill the database tables

The Moodle upgrade will take care of the updates. We will need to add a function into lib/upgradelib.php/upgrade_plugins() that will check all web service description.

Return values are filtered by the servers

Web service function should be able to return whatever they want. Each server should be looking at the web services description and returns the expected values.

Petr's Proposal

It can be found here.