|
|
| (167 intermediate revisions by 6 users not shown) |
| Line 1: |
Line 1: |
| {{Moodle_2.0}}
| | #REDIRECT [[Adding_a_web_service_to_a_plugin]] |
| 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]].<br/>
| |
| 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''': In our case we will use ''groups_create_group()'' from [http://cvs.moodle.org/moodle/group/ /group/lib.php]. Of course not every core function exists and in some other cases you could have to write them.
| |
| * '''the web service parameter types''': In our case we'll send a list of object. This object are groups, with id/name/courseid.
| |
| * '''the returned value types''': In our case we want to send back a list of group object with their id.
| |
| * '''the user capabilities''': In our case the user will need the ''moodle/course:managegroups'' capability.
| |
| | |
| == declare your web service functions/services ==
| |
| All web services function should be declare in the db/services.php of each component. Optionally, any larger services built up of several functions.
| |
| | |
| <code php>
| |
| $functions = array(
| |
| 'moodle_user_create_users' => array( //web service name (unique in all Moodle)
| |
| 'classname' => 'moodle_user_external', //class containing the function implementation
| |
| 'methodname' => 'create_users', //name of the function into the class
| |
| 'classpath' => 'user/externallib.php', //file containing the class (only used for core external function, not needed if your file is 'component/externallib.php'),
| |
| 'description' => 'create some users',
| |
| 'type' => 'write'
| |
| )
| |
| );
| |
| | |
| //following is optional
| |
| $services = array(
| |
| 'servicename' => array(
| |
| 'functions' => array ('functionname', 'secondfunctionname'), //web service function name
| |
| 'requiredcapability' => 'some/capability:specified',
| |
| 'restrictedusers' = >1,
| |
| 'enabled'=>0, //used only when installing the services
| |
| )
| |
| );
| |
| </code>
| |
| | |
| 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 static method calls by adding '_parameters' and '_returns' to the methodname value.
| |
| | |
| == define your external functions ==
| |
| 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.
| |
| <code php>
| |
| 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.
| |
| | |
| }
| |
| | |
| ...
| |
| | |
| }
| |
| </code>
| |
| | |
| == define your external 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.
| |
| <code php>
| |
| 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;
| |
| }
| |
| }
| |
| </code>
| |
| | |
| == 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.
| |
| | |
| == create your own client ==
| |
| | |
| ==See also==
| |
| * [[Web services]]
| |
| * [[External services security]]
| |
| * [[External services description]]
| |
| * [[Setting_up_a_web_service]]
| |
| | |
| [[Category:Web Services]]
| |
