Difference between revisions of "Web services API"

Jump to: navigation, search
(See also)
(Minor grammatical changes)
Line 1: Line 1:
 
==Overview==
 
==Overview==
  
The Web services API allows you to expose particular functions in your module (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.
  
Once you have done this, your functions will be available to admins to configure as part of their Web services over a given protocol like XML-RPC, REST or SOAP.
+
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 a web service function is done in one file: services.php
+
Exposing functions as Web service functions is done in one file called services.php.
  
 
== services.php ==
 
== services.php ==
* This file is located in the ''''db'''' folder of your plugin (https://docs.moodle.org/dev/Frankenstyle#Plugin_types)
+
* This file can be added to the '''db''' sub-folder of your [[Frankenstyle#Plugin_types|plugin]].
* This file contains one or two array. 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]]).
  
 
<code php>
 
<code php>
Line 26: Line 26:
 
</code>
 
</code>
  
* The second array declare the pre-build services.
+
* The second, optional array declares the pre-built services.
 
<code php>
 
<code php>
 
// OPTIONAL
 
// OPTIONAL
Line 41: Line 41:
 
</code>
 
</code>
  
Finally don't forget to increment the version.php of your plugin on every changes, otherwise Moodle will not know about them.
+
<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>
  
 
== Example ==
 
== 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. To make testing easy for you, the plugin is distributed with a test client in the folder /client.
+
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==

Revision as of 06:57, 7 March 2012

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.

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.

See also