Web services

Note: This page is a work-in-progress. Feedback and suggested improvements are welcome. Please join the discussion on moodle.org or use the page comments.

Moodle 2.0

Introduction

This page described the Web Services module implemented for Moodle 2.0
The tracker issue is here: MDL-12886
This module is been implemented by the DFWS Team and Moodle.

Implementation

Web Services module has been conceived in a purpose to be ported on different Moodle version, and also on different project. It has also for purpose to support multiple web service protocols (REST, SOAP, AMF, ...). Adding a new protocol support should be relatively easy.

How does it work

1. The client requests a token from the web services server. For that the client sends a username/password.
2. The web service server generates a token for this username and send it back to the client
3. The client calls a web service (module name, function name, and function parameters) and joins the token to it
4. The web service server authenticate the token, then call the matching web service function. The web service function is located in a external.php file. This external.php file contains all web service functions of for a module. The external.php file is located into the module folder.
5. The web service function check capability, and call Moodle core function.
6. The core function can return a result to the web service function. The web service can also return the result to the server. The server return the result to the client

Code example

Following some bits of code to understand the concept

REST_server.php

///REST params conversion

   $functionname = ... //retrieve function name from the REST parameters
   $modulename = ... //retrieve module name from the REST parameters
   $classname = $modulename.'_external';

/// Authentication process

   $token = ... //retrieve token from the REST parameters
   if (empty($token)) {
       if ($functionname != 'generate_token') {
           throw new moodle_exception('mustidentifyfirst');
       } else {
           ///authentication + token generation
           $username = ... //retrieve username from the REST parameters
           $password = ... //retrieve password from the REST parameters
           if ($token = generate_token($username,$password)) {
               return $token;
           } else {
               throw new moodle_exception('wrongusernamepassword');
           }
       }
   } else {
       ///the client is already identified
       $user = verify_token($token);
       if (empty($user)) {
           throw new moodle_exception('wrongidentification');
       }
       else {
           ///Load the user in order to get its context
           $USER = $user;
       }
   }

/// load the external class

   require_once($CFG->dirroot.$apipath.'external.php');
   $wsapi = new $classname();
   $description = $wsapi->get_function_webservice_description($functionname); //retrieve the web service description for this function

/// retrieve all rest params in an array

   $params = retrieve_rest_params ($description); //retrieve the REST params

/// call the web service function

   $result = call_user_func_array  ( $classname.'::'.$functionname, array($params));
   

   echo convert_into_rest_format(result);

external.php

final class user_external extends moodle_external {

   /**
    * Constructor - We set the description of this API in order to be access by Web service
    */
   function __construct () {
         $this->descriptions = array();
      ///The desciption of the web service
      ///
      ///'params', 'optionalparams' and 'return' are used to described the web services to the end user (can build WSDL file from these information)
         $this->descriptions['tmp_delete_user']   = array( 'params' => array('username'=> PARAM_ALPHANUM, 'mnethostid'=> PARAM_NUMBER),
                                                           'optionalparams' => array( ),
                                                           'return' => array('result' => PARAM_BOOL));

   /**
    * Delete a user
    * @global object $DB
    * @param array $params
    *  ->username      string
    *  ->mnethostid    integer
    * @return boolean true if success
    */
   static function tmp_delete_user($params) {
       global $DB,$USER;

       $user = $DB->get_record('user', array('username'=>$params['username'], 'mnethostid'=>$params['mnethostid']));
       if (has_capability('moodle/user:delete', get_context_instance(CONTEXT_SYSTEM))) {
           return delete_user($user); //this function is in moodlelib.php
       }
       else {
           throw new moodle_exception('couldnotdeleteuser');
       }
   }

}

?>

List of functions

All callable functions are declared into each external.php. A "description" array contains all function names, parameter names and types, and return type.