Development talk:External services description
From MoodleDocs
About the different alternatives describing the available WS
Hi, after reading the different alternatives, I'm inclined to implement something like the 3rd one. Having our custom structures to define the interface to the available web services seems really better than using "free-form" structures like "raw" arrays and objects or using harcoded keywords like "multiple" and so on.
Anyway, I've some (small) concerns about the example code used in the 3rd alternative, so I'm writing here how it should look like ideally IMO (rationale about changes is after the code):
class moodle_group_external extends external_api {
public static function add_member_parameters() {
return new external_single_structure(
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));
// actual implementation for adding one member goes here
}
public static function add_member_returns() { // Some concerns here. See below.
return null;
}
public static function add_members_parameters() {
return new external_multiple_structure(
'membership', self::add_member_parameters()
);
}
public static function add_members(array $membership) {
foreach($membership as $one) {
self::add_member($one->groupid, $one->userid);
}
}
public static function add_members_returns() { // BIG concerns here. See below.
return null;
}
public static function get_groups_parameters() {
return new external_multiple_structure(
'groupids', new external_single_structure(
array('groupid' => new external_param(PARAM_INT, 'some group id'))
)
);
}
public static function get_groups(array $groupids) {
$params = self::validate_prameters(self::get_groups_parameters(), array('groupids'=>$groupids));
// actual implementation for getting multiple groups goes here
}
public static function get_groups_returns() { // BIG concerns here. See below.
return new external_multiple_structure(
'groupids', 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() {
return new external_multiple_structure(
'users', 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(
'preference', 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(
'customfield', 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 ($users as $user) {
// actual implementation for creating one user goes here
}
}
public static function create_users_returns() { // BIG concerns here. See below.
return new external_multiple_structure(
'userids', new external_single_structure(
array('id' => new external_param(PARAM_INT, 'id of the created user'))
)
);
}
}
Changes from original code are:
- Small change in structure names. external_bulk_array renamed to external_multiple_structure and external_assoc_array to external_single_structure (note that structure can be changed to anything else. The important bits are the single/multiple ones vs. the assoc/bulk.
- Small change in external_multiple_structure so it has one 1st parameter giving one name to the structure.
- ...
