Web services API
Overview
The Web services API allows you to expose your plugin's functions (usually external functions) as Web services.
Once you have done this, your plugin's functions will be accessible to other systems through Web services using one of a number of protocols, like XML-RPC, REST or SOAP.
Exposing functions as Web service functions is done in one file called services.php.
services.php
- This file can be added to the db sub-folder of your plugin.
- This file contains one or two arrays. The first array declares your web service functions. Each of these declarations reference a function in your module (usually an external function).
<?php
$functions = array(
'local_PLUGINNAME_FUNCTIONNAME' => array( // local_PLUGINNAME_FUNCTIONNAME is the name of the web service function that the client will call.
'classname' => 'local_PLUGINNAME_external', // create this class in local/PLUGINNAME/externallib.php
'methodname' => 'FUNCTIONNAME', // implement this function into the above class
'classpath' => 'local/PLUGINNAME/externallib.php',
'description' => 'This documentation will be displayed in the generated API documentation
(Administration > Plugins > Webservices > API documentation)',
'type' => 'write', // the value is 'write' if your function does any database change, otherwise it is 'read'.
)
);
- The second, optional array declares the pre-built services.
// OPTIONAL
// During the plugin installation/upgrade, Moodle installs these services as pre-build services.
// A pre-build service is not editable by administrator.
$services = array(
'MY SERVICE' => array(
'functions' => array ('local_PLUGINNAME_FUNCTIONNAME'),
'restrictedusers' => 0, // if 1, the administrator must manually select which user can use this service.
// (Administration > Plugins > Web services > Manage services > Authorised users)
'enabled'=>1, // if 0, then token linked to this service won't work
)
);
Don't forget to increment the version number in the version.php file of your plugin whenever services.php changes, otherwise Moodle will not detect the changes.
Detailed tutorial
A more detailed tutorial for this system can be found at the following page:
Among other things, that tutorial explains how you define the parameters and return value of your function.
Example
You will find an example of a services.php file in the web service template plugin. This plugin contains a web service hello_world function.
Also, to make testing easy for you, the plugin is distributed with a test client in the client folder.
