Creating a web service and a web service function
Moodle 2.0
WORK IN PROGRESS
In this document you will learn how to create a web service function.
This document expect that you first read the administration manual Setting_up_a_web_service.
To explain how to write a new web service function, we will write a web service function create_groups($groups). This function create a group into a Moodle course.
This function will take a list of group object as parameters and it will return the same groups with their newly created id. If ever one group creation fails, the function will throw an exception, and no creation will happen.
We'll finally add the web service function to a core web service.
Preparation
We need to identify:
- the core functions: for our case we will use groups_create_group() from /group/lib.php. Of course not every core function exists and in some other cases you could have to write them.
- the parameter types: for our case we'll send a list of object. This object are groups, with id/name/courseid.
- the returned value types: for our case we want to send back a list of group object with their id.
- the user capabilities: for our case the user will need the moodle/course:managegroups capability.
declare the web service function
Web service functions are declared into db/services.php of each component. In our case create_groups() is a core external function, so we will add the function to /lib/db/services.php.
$functions = array(
'moodle_group_create_groups' => array( //web service function name
'classname' => 'moodle_group_external', //class containing the external function
'methodname' => 'create_groups', //external function name
'classpath' => 'group/externallib.php', //file containing the class/external function
'description' => 'Creates new groups.', //human readable description of the web service function
'type' => 'write', //database rights of the web service function (read, write)
),
);
Here you should ask yourself what is the difference between a web service function and an external function. Web service function could be considered as a redirection to the external function. The web service function name is the name that is served by web service server to the client. By this way the client doesn't know about the external functions.
The web service 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).
define the web service function description
This example includes param/return value descriptions. It has been extracted from the group/externallib.php. This file is a good example of externallib.php files.
class moodle_group_external extends external_api { //see following chapter 'function implementation' to have a look to the external_api class
public static function add_member_parameters() {
return new external_function_parameters(
array(
'groupid' => new external_value(PARAM_INT, 'some group id'),
'userid' => new external_value(PARAM_INT, 'some user id')
)
);
}
public static function add_member(...) {
...
}
public static function add_member_returns() {
return null;
}
}
define the external function
This example include a function implementation. It has been extracted from the group/externallib.php. This file is a good example of externallib.php files.
class moodle_group_external extends external_api { //see following chapter 'function implementation' to have a look to the external_api class
...
public static function add_member($groupid, $userid) {
$params = self::validate_parameters(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.
}
...
}
test your web service function with default Moodle test client
There is a central test client that can be accessed into webservice/testclient.php In order to add new function to be supported you will need to add a form into webservice/testclient_forms.php. Take example from the other implemented forms.
