Web services API

2017-07-31T14:45:29Z

Metasismedia:

==Overview==

The Web services API allows you to expose your plugin's functions (usually [[External functions API|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 [[Frankenstyle#Plugin_types|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 [[External functions API|an external function]]).

<code php>
<?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'.
'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.
)
);
</code>

* The second, optional array declares the pre-built services.
<code php>
// 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
)
);
</code>

<p class="note">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.</p>

== Detailed tutorial ==

A more detailed tutorial for this system can be found at the following page:
* [[Adding a web service to a plugin]]

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 [https://github.com/moodlehq/moodle-local_wstemplate 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.

==See also==

* [[Core APIs]]
* [[External functions API]]
* [[Web services API Changes]]

[[Category:Web_Services]]
[[Category:API]]

MoodleDocs - User contributions [en]

Web services API