|
|
| (41 intermediate revisions by 2 users not shown) |
| Line 1: |
Line 1: |
| {{Moodle_2.0}}
| | #REDIRECT [[Adding_a_web_service_to_a_plugin]] |
| | |
| = Simple example =
| |
| Have a look to the [https://github.com/moodlehq/moodle-local_wstemplate web service template]. It is a simple hello_world function.
| |
| | |
| = Complex example=
| |
| We will write a web service function ''create_groups($groups)''. This function create a group into a Moodle course. - actually the function already exists into Moodle. You can browse [https://github.com/moodle/moodle/blob/master/group/externallib.php Github repository] to have a look to the latest code.
| |
| | |
| == Write the function specification documentation ==
| |
| | |
| === functional ===
| |
| ''create_groups($groups)'' 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. '''Note:''' we now tend to go away from stopping execution when we write bulk operations. When an error occurs, we recommend to send an error message string instead to throw an exception (for new web service bulk functions).
| |
| | |
| === technical ===
| |
| * '''the core functions''': ''groups_create_group()'' from [http://cvs.moodle.org/moodle/group/ /group/lib.php].
| |
| * '''the parameter types''': a list of object. This object are groups, with id/name/courseid.
| |
| * '''the returned value types''': a list of group object with their id.
| |
| * '''the user capabilities''': ''moodle/course:managegroups''
| |
| | |
| == Write a simple test client ==
| |
| It is helpfull to start writing a web service test client. You will often discover use cases that you didn't think about. See [[Creating_a_web_service_client|How to create a web service client]].
| |
| | |
| == Declare the web service function ==
| |
| Web service functions are delcared/mapped in ''db/services.php'' files. ''create_groups()'' is a core external function, so it goes to [https://github.com/moodle/moodle/blob/master/lib/db/services.php#L31 /lib/db/services.php].
| |
| | |
| <code php>
| |
| $functions = array(
| |
| 'core_group_create_groups' => array( //web service function name
| |
| 'classname' => 'core_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)
| |
| ),
| |
| );
| |
| </code>
| |
| | |
| Web service functions should match the [https://docs.moodle.org/dev/Web_services_Roadmap#Naming_convention naming convention].
| |
| | |
| == Define the web service description ==
| |
| Some web service protocol need a full description of the web service function parameters and return value. For example we need to generate a full WSDL for SOAP if we expect a JAVA/.Net client to call our function. This WSDL need a complete and fully detailed description of the parameters.<br/>
| |
| Moreover we implemented a web service parameters validation process that also requires a full description of these parameters.<br/>
| |
| In conclusion, you must write these descriptions. They are not applied to the web service function but the external function, remember that the web service function is just a kind of redirection.<br/><br/>
| |
| | |
| Descriptions are usually located in a class inside a file named ''externallib.php'' in the component folder. You probably remember that we referenced this ''moodle_group_external'' class into [http://cvs.moodle.org/moodle/lib/db/ /lib/db/services.php]. Let's take a minute to talk about the [http://cvs.moodle.org/moodle/group/ /group/externallib.php] that we need to create.
| |
| | |
| This file will contain all external functions. They are all related to each other. In our case the externallib.php file will contain all ''group'' related functions. For each external function, we will have:
| |
| * the external function, calling a core function.
| |
| * a function describing the parameters of the external function
| |
| * a function describing the return values of the external function
| |
| | |
| === core_group_create_groups_parameters() ===
| |
| | |
| Now we'll have look to the description of the ''create_group($groups)'' parameters. All parameter descriptions are included in a function called ''externalfunctionname_parameters()''. In our case it will be ''create_groups_parameters()'' :
| |
| | |
| <code php>
| |
| require_once("$CFG->libdir/externallib.php");
| |
| | |
| class moodle_group_external extends external_api {
| |
| | |
| /**
| |
| * Returns description of method parameters
| |
| * @return external_function_parameters
| |
| */
| |
| public static function create_groups_parameters() {
| |
| return new external_function_parameters(
| |
| array(
| |
| 'groups' => new external_multiple_structure(
| |
| new external_single_structure(
| |
| array(
| |
| 'courseid' => new external_value(PARAM_INT, 'id of course'),
| |
| 'name' => new external_value(PARAM_TEXT, 'multilang compatible name, course unique'),
| |
| 'description' => new external_value(PARAM_RAW, 'group description text'),
| |
| 'enrolmentkey' => new external_value(PARAM_RAW, 'group enrol secret phrase'),
| |
| )
| |
| )
| |
| )
| |
| )
| |
| );
| |
| }
| |
| </code>
| |
| | |
| Ok you are probably already here :) We have to understand this function very well. There are different approaches to understand this function, here is my personal one.<br/>
| |
| The function ''xxx_parameters()'' always returns an ''external_function_parameters'' object. This object is initialized with an associative array. This array contains the parameter descriptions. If the external function has no parameters, this array will be empty (but present). If the external function has three parameters, it will have three elements, the keys being the parameters names.
| |
| Each of its element is a parameter description. A parameter can be a list (external_multiple_structure), an object (external_single_structure) or a primary type (external_value).
| |
| | |
| Our create_groups() function expects one parameter named ''groups'', so we will first write:
| |
| | |
| <code php>
| |
| /**
| |
| * Returns description of method parameters
| |
| * @return external_function_parameters
| |
| */
| |
| public static function create_groups_parameters() {
| |
| return new external_function_parameters(
| |
| array(
| |
| 'groups' => ...
| |
|
| |
| )
| |
| );
| |
| }
| |
| </code>
| |
| | |
| This ''groups'' parameter is a list of group. So we will write :
| |
| | |
| <code php>
| |
| 'groups' => new external_multiple_structure(
| |
| ...
| |
| )
| |
| </code>
| |
| | |
| An external_multiple_structure object (list) can be initialized with external_single_structure (object), external_value (primary type) or another external_multiple_structure (list). You will respectively obtain a list of a unique object type, a list of a unique primary type, or a list of a list. These last case being probably bad design.<br/>
| |
| In our case we want a list of group, a group being a object. Have a look on how would describe a group :
| |
| | |
| <code php>
| |
| new external_single_structure(
| |
| array(
| |
| 'courseid' => ...,
| |
| 'name' => ...,
| |
| 'description' => ...,
| |
| 'enrolmentkey' => ...,
| |
| )
| |
| )
| |
| </code>
| |
| | |
| From this code you can guess that an external_single_structure is initialized with an associative array containing the object attibutes.<br/>
| |
| Thus a list of group will be defined :
| |
| | |
| <code php>
| |
| 'groups' => new external_multiple_structure(
| |
| new external_single_structure(
| |
| array(
| |
| 'courseid' => ...,
| |
| 'name' => ...,
| |
| 'description' => ...,
| |
| 'enrolmentkey' => ...,
| |
| )
| |
| )
| |
| )
| |
| </code>
| |
| | |
| Each group attribute is a primary type. ''courseid'' is an integer. ''name'' is a string, ''description'' is a string, and ''enrolmentkey'' is also a string. To define a primary type we use the ''external_value'' object. This ''external_value'' is initialized with a non associative array containing three elements:
| |
| # the primary type | |
| # a human readable description
| |
| # is the parameter optional (if the parameter is mandatory we don't need this third element)
| |
| | |
| For example for the ''courseid'' and ''name'' attribut we would define:
| |
| | |
| <code php>
| |
| 'courseid' => new external_value(PARAM_INT, 'id of course'),
| |
| 'name' => new external_value(PARAM_TEXT, 'multilang compatible name, course unique'),
| |
| </code>
| |
| | |
| | |
| So our list of object description will be :
| |
| | |
| <code php>
| |
| 'groups' => new external_multiple_structure(
| |
| new external_single_structure(
| |
| array(
| |
| 'courseid' => new external_value(PARAM_INT, 'id of course'),
| |
| 'name' => new external_value(PARAM_TEXT, 'multilang compatible name, course unique'),
| |
| 'description' => new external_value(PARAM_RAW, 'group description text'),
| |
| 'enrolmentkey' => new external_value(PARAM_RAW, 'group enrol secret phrase'),
| |
| )
| |
| )
| |
| )
| |
| </code>
| |
| | |
| Now you should be able to understand this parameter description function. You also should be able to deduce how to write the return value description function.
| |
| | |
| === create_groups_return() ===
| |
| | |
| It's similar to create_groups_parameters(), but instead to describe the parameters, it describes the return values.
| |
| | |
| <code php>
| |
| public static function create_groups_returns() {
| |
| return new external_multiple_structure(
| |
| new external_single_structure(
| |
| array(
| |
| 'id' => new external_value(PARAM_INT, 'group record id'),
| |
| 'courseid' => new external_value(PARAM_INT, 'id of course'),
| |
| 'name' => new external_value(PARAM_TEXT, 'multilang compatible name, course unique'),
| |
| 'description' => new external_value(PARAM_RAW, 'group description text'),
| |
| 'enrolmentkey' => new external_value(PARAM_RAW, 'group enrol secret phrase'),
| |
| )
| |
| )
| |
| );
| |
| }
| |
| </code>
| |
| | |
| === Required, Optional or Default value ===
| |
| A value can be VALUE_REQUIRED, VALUE_OPTIONAL, or VALUE_DEFAULT. If not mentioned, a value is VALUE_REQUIRED by default.
| |
| | |
| <code php>
| |
| 'yearofstudy' => new external_value(PARAM_INT, 'year of study',VALUE_DEFAULT, 1979),
| |
| </code>
| |
| | |
| * VALUE_REQUIRED - if the value is not supplied => the server throws an error message
| |
| * VALUE_OPTIONAL - if the value is not supplied => the value is ignored
| |
| * VALUE_DEFAULT - if the value is not supplied => the default value is used
| |
| | |
| == Implement the external function ==
| |
| We declared our web service function and we defined the external function parameters and return values. We will now implement the external function:
| |
| | |
| <code php>
| |
| /**
| |
| * Create groups
| |
| * @param array $groups array of group description arrays (with keys groupname and courseid)
| |
| * @return array of newly created groups
| |
| */
| |
| public static function create_groups($groups) { //Don't forget to set it as static
| |
| global $CFG, $DB;
| |
| require_once("$CFG->dirroot/group/lib.php");
| |
| | |
| $params = self::validate_parameters(self::create_groups_parameters(), array('groups'=>$groups));
| |
| | |
| $transaction = $DB->start_delegated_transaction(); //If an exception is thrown in the below code, all DB queries in this code will be rollback.
| |
| | |
| $groups = array();
| |
| | |
| foreach ($params['groups'] as $group) {
| |
| $group = (object)$group;
| |
| | |
| if (trim($group->name) == '') {
| |
| throw new invalid_parameter_exception('Invalid group name');
| |
| }
| |
| if ($DB->get_record('groups', array('courseid'=>$group->courseid, 'name'=>$group->name))) {
| |
| throw new invalid_parameter_exception('Group with the same name already exists in the course');
| |
| }
| |
| | |
| // now security checks
| |
| $context = get_context_instance(CONTEXT_COURSE, $group->courseid);
| |
| self::validate_context($context);
| |
| require_capability('moodle/course:managegroups', $context);
| |
| | |
| // finally create the group
| |
| $group->id = groups_create_group($group, false);
| |
| $groups[] = (array)$group;
| |
| }
| |
| | |
| $transaction->allow_commit();
| |
| | |
| return $groups;
| |
| }
| |
| </code>
| |
| | |
| === Parameter validation ===
| |
| <code php>
| |
| $params = self::validate_parameters(self::create_groups_parameters(), array('groups'=>$groups));
| |
| </code>
| |
| This ''validate_parameters'' function validates the external function parameters against the description. It will return an exception if some required parameters are missing, if parameters are not well-formed, and check the parameters validity. It is essential that you do this call to avoid potential hack.
| |
| | |
| '''Important:''' the parameters of the external function and their declaration in the description '''must be the same order'''. In this example we have only one parameter named $groups, so we don't need to worry about the order.
| |
| | |
| === Context and Capability checks ===
| |
| | |
| In a long term, in Moodle 2.0, all context/capability checks will disappear from the core functions and will be located into the external functions. Don't forget them.
| |
| <code php>
| |
| /// now security checks
| |
| $context = get_context_instance(CONTEXT_COURSE, $group->courseid);
| |
| self::validate_context($context);
| |
| require_capability('moodle/course:managegroups', $context);
| |
| </code>
| |
| | |
| === Exceptions===
| |
| You can throws exception. There are automatically handle by Moodle web service servers.
| |
| <code php>
| |
| //Note: it is good practice to add detailled information in $debuginfo,
| |
| // and only send back a generic exception message when Moodle DEBUG mode < NORMAL.
| |
| // It's what we do here throwing the invalid_parameter_exception($debug) exception
| |
| throw new invalid_parameter_exception('Group with the same name already exists in the course');
| |
| </code>
| |
| | |
| === Correct return values ===
| |
| The return values will be validated by the Moodle web service servers:
| |
| * return values contain some values not described => these values will be skipped.
| |
| * return values miss some required values (VALUE_REQUIRED) => the server will return an error.
| |
| * return values types don't match the description (int != PARAM_ALPHA) => the server will return an error
| |
| | |
| == Add the web service function into a service ==
| |
| You can pre-build a service including any functions, so the Moodle administrator doesn't need to do it. Add into [http://cvs.moodle.org/moodle/lib/db/ /lib/db/services.php]:
| |
| | |
| <code php>
| |
| $services = array(
| |
| 'groupservice' => array( //the name of the web service
| |
| 'functions' => array ('moodle_add_groups', 'moodle_create_groups'), //web service functions of this service
| |
| 'requiredcapability' => 'some/capability:specified', //if set, the web service user need this capability to access
| |
| //any function of this service
| |
| 'restrictedusers' = >1, //if enabled, the Moodle administrator must link some user to this service
| |
| //into the administration
| |
| 'enabled'=>0, //if enabled, the service can be reachable on a default installation
| |
| )
| |
| );
| |
| </code>
| |
| | |
| Note: it is not possible for an administrator to add/remove any function from a pre-built service.
| |
| | |
| ==See also==
| |
| * [https://docs.moodle.org/20/en/Web_services Web services]
| |
| * [[Creating_a_web_service_client|Implement a web service client]]
| |
| | |
| Specification:
| |
| * [[External services security]]
| |
| * [[External services description]]
| |
| | |
| [[Category:Web Services]] | |
