External services description

Jerome's proposal

Database tables should only contain data that can be managed by administrator
All the web services description should be in an array into each external.php file
a cron job browses all external files, checkes the description and updates the database (if functions/services disappeared or are created)

external_functions table

List of external functions. Created automatically by parsing of external files.

Field	Type	Default	Description
id	int(10)	auto-incrementing
name	varchar(150)		Name of function - Appears on the admin page
enabled	int(1)		function enabled, function might be disabled for security reasons - The only field editable by administrator !
phpfile	varchar(255)		location where function defined - Needed for identifying

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.
I removed contextrestriction because the context should checked into the external function. Why should we save this information?

external_services table

Service is defined as a group of 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)		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.

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 row because the capabilities are checked into the external functions. These checks are hard coded into the external function as anywhere else into Moodle.
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

PHP array description

$this->descriptions['function_name'] = array( 'params' => array('params_name'=> PARAM_STRING),

                                      'optionalparams' => array( ),
                                      'return' => array('list:param_1' => 
                                                           array('attribut_1' => PARAM_INT, 
                                                                 'attribut_2' => PARAM_STRING, 
                                                                 'attribut_3' => PARAM_INT)));

Explanation:

base is:

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

                                                           'optionalparams' => array( ),
                                                           'return' => array());

when a param/return is a list so it should be called 'list:param_name'
when a param/return is not a list so it's either a primary type (e.g. PARAM_STRING), either a object (e.g. array)
params and optionalparams have to follow the exact order of the function

Way to fill the database tables

A cron job update the tables

Return values are filtered by the servers

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

Documentation