External services description: Difference between revisions
Line 144: | Line 144: | ||
| | | | ||
| foreign key, reference external_functions.id | | foreign key, reference external_functions.id | ||
|} | |} | ||
Revision as of 05:16, 11 September 2009
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 service.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,... | |
servicelibpath | varchar(255) | location where function defined - Needed for identifying | |
contextrestriction | int(1) | extra information - some functions may support context restrictions | |
requiredlogin | 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.
New function: validate_context_restriction($currentcontext)
Each functions that supports restrictions must:
- 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.
- 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. |
customname | varchar(150) | As a custom service name cannot be found into lang files, we need a field for that | |
(version) | varchar(10) | version string - it should be implemented later |
Note about Petr's Proposal:
- requiredCapability, we will test if a user has the right to use the service checking that an association exists.
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 |
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;
$functions = array(
'functionname' => array(
'requiredlogin' => 0,
'params' => $params,
'optionalinformation' => 'Human readable text: "object" and "primarytype" parameters are optionals',
'return' => $return,
'capabilities' => array()
),
'secondfunctionname' => array(
'requiredlogin' => 1,
'params' => $params,
'optionalinformation' => 'Human readable text: "object" and "primarytype" parameters are optionals',
'return' => $return,
'capabilities' => array()
)
);
Note about the code:
- component: the component is not defined into the function description cause it will get the name of the plugin (if it's not a plugin, so the name will be 'core')
- service: no service are created here, neither any service/function association.
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.