External services description: Difference between revisions
| Line 442: | Line 442: | ||
<code php> | <code php> | ||
class moodle_user_external extends external_api { | class moodle_user_external extends external_api { | ||
public static function create_users($ | public static function create_users($users) | ||
$params = self::validate_prameters(self::create_users_parameters(), array('users'=>$users)); //ws object are associative array, ws list are non associative array | $params = self::validate_prameters(self::create_users_parameters(), array('users'=>$users)); //ws object are associative array, ws list are non associative array | ||
foreach ($users as $user) { | foreach ($users as $user) { | ||
// all the parameter/behavioural checks and security | // all the parameter/behavioural checks and security constraints go here, | ||
// throwing exceptions if | // throwing exceptions if needed and and calling low level (userlib) | ||
// add_user() function that will be one in charge of the functionality without | // add_user() function that will be one in charge of the functionality without | ||
// further checks. | // further checks. | ||
Revision as of 20:47, 6 October 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) | unique 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 | |
| methodname | 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 |
| 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 |
| component | varchar(100) | NULL | Component where service defined - null means custom service defined in admin UI. |
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 | |
| functionname | varchar(200) | name of external service, references external_functions.name; the string value here simplifies service discovery and maintenance |
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 | |
| iprestriction | char(255) | restrict access to some ips or subnets only | |
| validuntil | int(10) | invalidate after | |
| timecreated | int(10) | time when this record added |
PHP array description
We need to describe the services in detail, including input and output, so that we can:
- help programmers quickly understand what they have to send and what to expect
- validate all incoming data as automatically as possible for security/correctness
- generate WSDL files for SOAP
- generate documentation for other protocols
There are three main parts working together to do this:
services.php
In the db/services.php of each component, is a structure something like this to describe the web service functions, and optionally, any larger services built up of several functions.
$functions = array(
'moodle_user_create_users' => array(
'classname' => 'moodle_user_external',
'methodname' => 'create_users',
'classpath' => 'user/externallib.php',
)
);
$services = array(
'servicename' => array(
'functions' => array ('functionname', 'secondfunctionname'),
'requiredcapability' => 'some/capability:specified',
'restrictedusers' = >1,
'enabled'=>0, //used only when installing the services
)
);
The function name is arbitrary, but it must be globally unique so we highly recommend using the component name as prefix (and "moodle" for core functions).
The actual param description and description of returned values can be obtained from the same class by adding '_parameters' and '_returns' to the methodname value. We can not use object property default values for this because function and new instances of objects are not allowed there.
externallib.php
In the file referenced as the location for the web service function, there are also complete descriptions of the parameters required.
Base description classes:
abstract class external_description {
public $desc;
public $required;
public function __construct($desc, $required) {
$this->desc = $desc;
$this->required = $required;
}
}
class external_param extends external_description {
public $type;
public $default;
public $allownull;
public function __construct($type, $desc=, $required=true, $default=null, $allownull=true) {
parent::_construct($desc, $required);
$this->type = $type;
$this->default = $default;
$this->allownull = $allownull;
}
}
class external_single_structure extends external_description {
public $keys;
public function __construct(array $keys, $desc=, $required=true) {
parent::_construct($desc, $required);
$this->keys = $keys; //key=>external_description
}
}
class external_multiple_structure extends external_description {
public $content;
public function __construct(external_description $content, $desc=, $required=true) {
parent::_construct($desc, $required);
$this->content = $content;
}
}
class external_function_parameters extends external_single_structure {
}
Externallib.php examples:
class moodle_group_external extends external_api {
public static function add_member_parameters() {
return new external_function_parameters(
array(
'groupid' => new external_param(PARAM_INT, 'some group id'),
'userid' => new external_param(PARAM_INT, 'some user id')
)
);
}
public static function add_member($groupid, $userid) {
$params = self::validate_prameters(self::add_member_parameters(), array('groupid'=>$groupid, 'userid'=>$userid));
// all the parameter/behavioural checks and security constrainsts go here,
// throwing exceptions if neeeded and and calling low level (grouplib)
// add_member() function that will be one in charge of the functionality without
// further checks.
}
public static function add_member_returns() {
return null;
}
public static function add_members_parameters() {
return new external_function_parameters(
array(
'membership' => new external_multiple_structure(
self::add_member_parameters()
)
)
);
}
public static function add_members(array $membership) {
$params = self::validate_prameters(self::add_members_parameters(), array('membership'=>$membership));
foreach($params['membership'] as $one) { // simply one iterator over the "single" function if possible
self::add_member($one->groupid, $one->userid);
}
}
public static function add_members_returns() {
return null;
}
public static function get_groups_parameters() {
return new external_function_parameters(
array(
'groups' => new external_multiple_structure(
new external_single_structure(
array(
'groupid' => new external_param(PARAM_INT, 'some group id')
)
)
)
)
);
}
public static function get_groups(array $groups) {
$params = self::validate_prameters(self::get_groups_parameters(), array('groups'=>$groups));
// all the parameter/behavioural checks and security constrainsts go here,
// throwing exceptions if neeeded and and calling low level (grouplib)
// get_groups() function that will be one in charge of the functionality without
// further checks.
}
public static function get_groups_returns() {
return new external_multiple_structure(
new external_single_structure(
array(
'id' => new external_param(PARAM_INT, 'some group id'),
'name' => new external_param(PARAM_TEXT, 'multilang compatible name, course unique'),
'description' => new external_param(PARAM_RAW, 'just some text'),
'enrolmentkey' => new external_param(PARAM_RAW, 'group enrol secret phrase')
)
)
);
}
}
class moodle_user_external extends external_api {
public static function create_users_parameters() {
new external_function_parameters(
array(
'users' => new external_multiple_structure(
new external_single_structure(
array(
'username' => new external_param(PARAM_USERNAME, 'Username policy is defined in Moodle security config'),
'password' => new external_param(PARAM_RAW, 'Moodle passwords can consist of any character'),
'firstname' => new external_param(PARAM_NOTAGS, 'The first name(s) of the user'),
'lastname' => new external_param(PARAM_NOTAGS, 'The family name of the user'),
'email' => new external_param(PARAM_EMAIL, 'A valid and unique email address'),
'auth' => new external_param(PARAM_AUTH, 'Auth plugins include manual, ldap, imap, etc', false),
'confirmed' => new external_param(PARAM_NUMBER, 'Active user: 1 if confirmed, 0 otherwise', false),
'idnumber' => new external_param(PARAM_RAW, 'An arbitrary ID code number perhaps from the institution', false),
'emailstop' => new external_param(PARAM_NUMBER, 'Email is blocked: 1 is blocked and 0 otherwise', false),
'lang' => new external_param(PARAM_LANG, 'Language code such as "en_utf8", must exist on server', false),
'theme' => new external_param(PARAM_THEME, 'Theme name such as "standard", must exist on server', false),
'timezone' => new external_param(PARAM_ALPHANUMEXT, 'Timezone code such as Australia/Perth, or 99 for default', false),
'mailformat' => new external_param(PARAM_INTEGER, 'Mail format code is 0 for plain text, 1 for HTML etc', false),
'description' => new external_param(PARAM_TEXT, 'User profile description, as HTML', false),
'city' => new external_param(PARAM_NOTAGS, 'Home city of the user', false),
'country' => new external_param(PARAM_ALPHA, 'Home country code of the user, such as AU or CZ', false),
'preferences' => new external_multiple_structure(
new external_single_structure(
array(
'type' => new external_param(PARAM_ALPHANUMEXT, 'The name of the preference'),
'value' => new external_param(PARAM_RAW, 'The value of the preference')
)
), 'User preferences', false),
'customfields' => new external_multiple_structure(
new external_single_structure(
array(
'type' => new external_param(PARAM_ALPHANUMEXT, 'The name of the custom field'),
'value' => new external_param(PARAM_RAW, 'The value of the custom field')
)
), 'User custom fields', false)
)
)
)
)
);
}
public static function create_users(array $users) {
$params = self::validate_prameters(self::create_users_parameters(), array('users'=>$users));
foreach ($params['users'] as $user) {
// all the parameter/behavioural checks and security constrainsts go here,
// throwing exceptions if neeeded and and calling low level (userlib)
// add_user() function that will be one in charge of the functionality without
// further checks.
}
}
public static function create_users_returns() {
return new external_multiple_structure(
new external_param('userid', PARAM_INT, 'id of the created user')
);
}
}
Note the use of Moodle-oriented PARAM_XXXX constants to define the format of each field. These are used by the validation function to verify the data and throw an exception and abort the operation completely if the data changed during cleaning (ie it was malformed).
Params
We use the clean_param function to check data. We have added some new checks for common Moodle data so that we get better cleaning. eg
...
case PARAM_AUTH:
$param = clean_param($param, PARAM_SAFEDIR);
if (exists_auth_plugin($param)) {
return $param;
} else {
return ;
}
case PARAM_LANG:
$param = clean_param($param, PARAM_SAFEDIR);
$langs = get_list_of_languages(false, true);
if (in_array($param, $langs)) {
return $param;
} else {
return ; // Specified language is not installed
}
case PARAM_THEME:
$param = clean_param($param, PARAM_SAFEDIR);
if (file_exists($CFG->dirroot.'/theme/'.$param)) {
return $param;
} else {
return ; // Specified theme is not installed
}
...
Function implementation
The function are generally stored in externallib.php files, as methods in a class that extends 'external_api'. The actual file location is referenced by 'classpath' in the services.php description.
class moodle_user_external extends external_api {
public static function create_users($users)
$params = self::validate_prameters(self::create_users_parameters(), array('users'=>$users)); //ws object are associative array, ws list are non associative array
foreach ($users as $user) {
// all the parameter/behavioural checks and security constraints go here,
// throwing exceptions if needed and and calling low level (userlib)
// add_user() function that will be one in charge of the functionality without
// further checks.
}
}
}
Note: there is more examples in the previous chapter
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.
Some bulk requests may end up in the middle of processing elements, these partial failures should be indicated by special exceptions classes which include list of completed elements and original exception.
Petr's Proposal
It can be found here.
