Note:

If you want to create a new page for developers, you should create it on the Moodle Developer Resource site.

Web services API: Difference between revisions

From MoodleDocs
(4 intermediate revisions by 2 users not shown)
Line 1: Line 1:
==Overview==
==Overview==
The Web services API allows you to expose your plugin's functions (usually [[External functions API|external functions]]) as Web services.
The Web services API allows you to expose your plugin's functions (usually [[External functions API|external functions]]) as Web services.


Line 6: Line 5:


Exposing functions as Web service functions is done in one file called services.php.
Exposing functions as Web service functions is done in one file called services.php.
== services.php ==
== services.php ==
* This file can be added to the '''db''' sub-folder of your [[Frankenstyle#Plugin_types|plugin]].
* 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]]).
* 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]]).
 
<syntaxhighlight lang="php">
<code php>
<?php
<?php


$functions = array(
$functions = array(
         'local_PLUGINNAME_FUNCTIONNAME' => array( // local_PLUGINNAME_FUNCTIONNAME is the name of the web service function that the client will call.                                                                                 
         '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
                 'classname'  => 'component\external[\optional\sub\namespaces\classname', // create this class in componentdir/classes/external
                 'methodname'  => 'FUNCTIONNAME', // implement this function into the above class
                 '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  
                 'description' => 'This documentation will be displayed in the generated API documentation  
                                           (Administration > Plugins > Webservices > API documentation)',
                                           (Administration > Plugins > Webservices > API documentation)',
Line 27: Line 23:
         )
         )
);
);
</code>
</syntaxhighlight>
 
* The second, optional array declares the pre-built services.
* The second, optional array declares the pre-built services.
<code php>
<syntaxhighlight lang="php">
// OPTIONAL
// OPTIONAL
// During the plugin installation/upgrade, Moodle installs these services as pre-build services.  
// During the plugin installation/upgrade, Moodle installs these services as pre-build services.  
Line 43: Line 38:
         )
         )
);
);
</code>
</syntaxhighlight>
 
<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>
<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 ==
== Detailed tutorial ==
A more detailed tutorial for this system can be found at the following page:
A more detailed tutorial for this system can be found at the following page:
* [[Adding a web service to a plugin]]
* [[Adding a web service to a plugin]]
Among other things, that tutorial explains how you define the parameters and return value of your function.
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==
==See also==
* [[Core APIs]]
* [[Core APIs]]
* [[External functions API]]
* [[External functions API]]
* [[Web services API Changes]]
* [[Web services API Changes]]
 
* [[Session locks#Read only sessions in web services]]
[[Category:Web_Services]]
[[Category:Web_Services]]
[[Category:API]]
[[Category:API]]

Revision as of 03:07, 16 March 2022

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'   => 'component\external[\optional\sub\namespaces\classname', // create this class in componentdir/classes/external
                'methodname'  => 'FUNCTIONNAME', // implement this function into the above class
                '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 required by the function (those in a require_capability() call) (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, 'local_mobile')    // 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 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
                'shortname'=>'myservice' //the short name used to refer to this service from elsewhere including when fetching a token
        )
);

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.

See also