Web service API

Web service API

 

 

Overview

The web service API allows you to expose the functionality of your plugin (usually external functions ) as a web service.

Once you've done this, your plugin's functionality can be accessed by other systems via Web services using many protocols like XML-RPC, REST or SOAP.

Exposing functions as web service functions is done in a file called services.php.

services.php

• This file can be added to your plugin 's database subfolder . ( plugin /db/services.php ) _
• This file contains one or two arrays. The first array declares your web service functions. Each of these declarations refers to a function in the module (usually an external function ).

$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'.
                'ajax'        => true, // true/false if you allow this web service function to be callable via ajax
                'capabilities'  => 'moodle/xxx:yyy, addon/xxx:yyy',  // List the capabilities used in the function (missing capabilities are displayed for authorised users and also for manually created tokens in the web interface, this is just informative).
                'services' => array(MOODLE_OFFICIAL_MOBILE_SERVICE)    // Optional, only available for Moodle 3.1 onwards. List of built-in services (by shortname) where the function will be included. Services created manually via the Moodle interface are not supported.
        )
);

 

• The second optional array declares prebuilt 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
        )
);

 

Whenever services.php changes, don't forget to increment the version number in the plugin's version.php file, otherwise Moodle won't be able to detect the change.

detailed tutorial

A more detailed tutorial on this system can be found on the following pages:

• Add web service to plugin

In addition to this, the tutorial shows how to define the parameters and return values ​​of a function.

example

You will find an example of a services.php file in the Web Services Templates plugin . This plugin contains a web service hello_world function.

Also, to make testing easy, the plugin is distributed with the test client in the clients folder .