External services description: Difference between revisions
Line 85: | Line 85: | ||
| int(1) | | int(1) | ||
| 0 | | 0 | ||
| service enabled, for security reasons some services may be disabled - | | service enabled, for security reasons some services may be disabled- administrators may disable any service via the admin UI | ||
|- | |- | ||
| custom | | custom | ||
Line 102: | Line 102: | ||
| 1 means on users explicitly listed in external_services_users may access this service, 0 means any user may use this service | | 1 means on users explicitly listed in external_services_users may access this service, 0 means any user may use this service | ||
|} | |} | ||
===external_services_functions table=== | ===external_services_functions table=== |
Revision as of 12:52, 13 September 2009
Moodle 2.0
Purpose
This document explains how we describe and where we store the web service functions in Moodle 2.0.
We store function descriptions in the component/db/services.php file. Web services functions will be located in externallib.php files - this file name is not mandatory, but is strongly recommended.
Descriptions will be parsed 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. This table maps the web service name to the actual implementation of that function.
Field | Type | Default | Description |
---|---|---|---|
id | int(10) | auto-incrementing | |
name | varchar(200) | name of the external function used in web service protocols - a unique identifier for each function; ex.: core_get_users, mod_assignment_submit | |
classname | varchar(100) | name of the class that contains method implementation; ex.: core_user_external, mod_assignment_external | |
method | varchar(100) | static method; ex.: get_users, submit | |
classpath | varchar(255) | NULL | optional path to file with class definition - recommended for core classes only, null means use component/externallib.php; this path is relative to dirroot; ex.: user/externallib.php |
component | varchar(100) | Component where function defined, needed for automatic updates. Service description file is found in the db folder of this component. |
Detailed function description is stored as a complex PHP array in db/services.php file.
external_services table
Service is defined as a group of web service functions. The main purpose of these services is to allow defining of granular access control for multiple external systems.
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- administrators may disable any service via the admin UI |
custom | int(1) | 0 | Custom local service, created manually by admin or some other way. |
requiredcapability | varchar(255) | NULL | if capability name specified, user needs to have this permission in security context or in system context if context restriction not specified |
restrictedusers | int(1) | 1 | 1 means on users explicitly listed in external_services_users may access this service, 0 means any user may use this service |
external_services_functions table
Lists all functions that are available in each service.
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 the params automatically
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(
'classname_external:functionname' => array(
'path' => 'servicelibpath',
'requiredlogin' => 0,
'params' => $params,
'optionalinformation' => 'Human readable text: "object" and "primarytype" parameters are optionals',
'return' => $return,
'capabilities' => array()
),
'classname_external:secondfunctionname' => array(
'path' => 'servicelibpath',
'requiredlogin' => 1,
'params' => $params,
'optionalinformation' => 'Human readable text: "object" and "primarytype" parameters are optionals',
'return' => $return,
'capabilities' => array()
)
);
$services = array(
'servicename' => array(
'functions' => array ('functioname' => 'componentname', 'functionname2' => 'componentname2'),
'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: the services can reference any functions (do not depend of this plugin) => the web services dev needs to know the component name format!
Function implementation
The function are store into servicelib.php classes. These classes can be found anywhere and are referenced by the servicelibpath into the function description. However it would be a common practice to place them in obvious places like a plugin lib folder.
final class componentname_service {
static public function functioname ($params) {
clean_function_params('functioname', $params);
/// specific function code
/// ...
}
}
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.