Note:

If you want to create a new page for developers, you should create it on the Moodle Developer Resource site.

External services description

From MoodleDocs
Revision as of 02:29, 31 August 2009 by jerome mouneyrac (talk | contribs)

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
  • Moodle upgrade will browse all external files, check the description and update the database (if functions/services disappeared or are created)

Administration pages

The admin will be able to enable services and functions. By default all services and function will be disabled.

  • enable a service => enable all the functions into this service
  • enable a function => enable the services that the function is associated with. It does not change any other function status.
  • an option will enable/disable all services
  • an option will enable/disable all functions (into service settings page)

The admin will also be able to create a service, selecting any existing function.

external_functions table

List of external functions.


Field Type Default Description
id int(10) auto-incrementing
component varchar(100) Component where function defined, needed for automatic updates.
name varchar(150) Name of function - Appears on the admin page
enabled int(1) 0 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
contextrestriction int(1) extra information - some functions may support context restrictions


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 functions.


Field Type Default Description
id int(10) auto-incrementing
component varchar(100) Component where service defined, needed for automatic updates.
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.

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

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

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

                                      'service' => 'service_name',
                                      'humanreadabledescription' => get_string('function_name_desc','webservices'),
                                      'requiredlogin' => 0,
                                      'params' => array('param_name'=> PARAM_STRING),
                                      'optionalparams' => array( ),
                                      'return' => array('list:param_1' => 
                                                           array('attribut_1' => PARAM_INT, 
                                                                 'attribut_2' => PARAM_STRING, 
                                                                 'attribut_3' => PARAM_INT)));

The common array construction to any function is: $this->descriptions['function_name'] = array(

                                      'service' => 'service_name', 
                                      'params' => array(),
                                      'optionalparams' => array( ),
                                      'return' => array());

  • when a param/return is a list, it should be called 'list:param_name'
  • when a param/return is not a list, 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

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

External 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.