|
|
| (146 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''': for 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 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 [http://cvs.moodle.org/moodle/lib/db/ /lib/db/services.php].
| |
| | |
| <code 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)
| |
| ),
| |
| );
| |
| </code>
| |
| | |
| 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 ==
| |
| Some web service needs 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.<br/>
| |
| Moreover we implemented a web service parameters validation process that require a full description of these parameters.<br/>
| |
| In conclusion, you must write these descriptions. These descriptions are not applied on 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 into a class into an externallib.php in the component folder. You probably remember that we referenced this class ''moodle_group_external'' into the db/service.php. Before to talk about the description let talk a minute about this externallib.php file.
| |
| | |
| Have a look to the following description of the ''create_group($groups)'' parameters
| |
| | |
| <code php>
| |
| /**
| |
| * 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>
| |
| | |
| == define the external function ==
| |
| | |
| == Add the web service function into a service ==
| |
| In some specific case we could want to set a service by default, so the Moodle administrator doesn't need to set a new one. We can do that by writing the following code:
| |
| | |
| <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>
| |
| | |
| In this code we created a service called ''groupservice''. This service contains two functions ''moodle_add_groups''/''moodle_create_groups''. <br/>
| |
| This possibility to preset a service exists to facilitate the administrator life. He can easily enable a bunch of function. <br/>
| |
| However it is not possible for an administrator to add/remove any function from preset service. For security purpose, it is not a recommended to preset a service.
| |
| | |
| == test the web service function ==
| |
| Moodle is bundled with a test client that can be accessed into [http://cvs.moodle.org/moodle/webservice/ webservice/testclient.php]<br/>
| |
| In order to support our function we will need to add a form into [http://cvs.moodle.org/moodle/webservice/ webservice/testclient_forms.php].
| |
| | |
| == create your own client ==
| |
| | |
| ==See also==
| |
| * [[Web services]]
| |
| * [[External services security]]
| |
| * [[External services description]]
| |
| * [[Setting_up_a_web_service]]
| |
| | |
| [[Category:Web Services]]
| |
