Webservice protocols

Jump to: navigation, search

Introduction

Web service protocol plugins are web service servers. These servers let external applications call Moodle web service functions in an specific protocol: REST / AMF / SOAP /XML-RPC / ...

Examples

The easiest example is the REST server.

File structure

webservice/myprotocol/db/access.php

Since Moodle 3.0 protocols capabilities don't have risks attached. See MDL-50613 for more information.

<?php
 
/**
 * myprotocol server related capabilities
 *
 * @package    webservice_myprotocol
 * @category   access
 * @copyright  20XX Your Name
 * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 */
 
$capabilities = array(
 
    'webservice/myprotocol:use' => array(
        'captype' => 'read', // in fact this may be considered read and write at the same time
        'contextlevel' => CONTEXT_COURSE, // the context level should be probably CONTEXT_MODULE
        'archetypes' => array(
        ),
    ),
 
);

webservice/myprotocol/lang/en/webservice_myprotocol.php

<?php
 
/**
 * Strings for component 'webservice_myprotocol', language 'en', branch 'MOODLE_XX_STABLE'
 *
 * @package    webservice_myprotocol
 * @category   string
 * @copyright  20XX Your Name
 * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 */
 
$string['pluginname'] = 'myprotocol protocol';
$string['myprotocol:use'] = 'Use myprotocol protocol';

webservice/myprotocol/server.php

This is the entry point of your server. The web service clients will call this file with the web service function name/parameters and the web service token. In this file you could want to catch some other $_REQUEST parameters as the REST server does. But it's most likely that very few changes are going to be done here.

<?php
/**
 * myprotocol web service entry point. The authentication is done via tokens.
 *
 * @package    webservice_myprotocol
 * @copyright  20XX Your Name
 * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 */
 
/**
 * NO_DEBUG_DISPLAY - disable moodle specific debug messages and any errors in output
 */
define('NO_DEBUG_DISPLAY', true);
 
/**
 * NO_MOODLE_COOKIES - no cookies with web service
 */
define('NO_MOODLE_COOKIES', true);
 
require('../../config.php');
require_once("$CFG->dirroot/webservice/myprotocol/locallib.php");
 
if (!webservice_protocol_is_enabled('myprotocol')) {
    die;
}
 
$server = new webservice_rest_server(WEBSERVICE_AUTHMETHOD_PERMANENT_TOKEN);
$server->run();
die;

webservice/myprotocol/locallib.php

That's where all the magic happens. Have a look how the REST server or the Zend servers extend webservice_base_server.

<?php
 
/**
 * myprotocol web service implementation classes and methods.
 *
 * @package    webservice_myprotocol
 * @copyright  20XX Your Name
 * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 */
 
require_once("$CFG->dirroot/webservice/lib.php");
 
/**
 * myprotocol service server implementation.
 *
 * @package    webservice_myprotocol
 * @copyright  20XX Your Name
 * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 */
class webservice_myprotocol_server extends webservice_base_server {
 
    /**
     * Contructor
     *
     * @param string $authmethod authentication method of the web service (WEBSERVICE_AUTHMETHOD_PERMANENT_TOKEN, ...)
     */
    public function __construct($authmethod) {
        parent::__construct($authmethod);
    }
 
    /**
     * This method parses the $_REQUEST
     */
    protected function parse_request() {
       //Retrieve the user credentials (token / ...), the web service function parameters, ...
       $this->token = isset($_REQUEST['wstoken']) ? $_REQUEST['wstoken'] : null;
       unset($_REQUEST['wstoken']);
 
       $this->functionname = isset($_REQUEST['wsfunction']) ? $_REQUEST['wsfunction'] : null;
       unset($_REQUEST['wsfunction']);
 
       $this->parameters = $_REQUEST;
    }
 
    /**
     * Send the result of function call to the WS client
     */
    protected function send_response() {
 
        // Check that the returned values are valid
        // sometimes it is not necessary like for Zend servers where 
        // the cleaning is done in service_class_method_body() of the webservice_zend_server class
        try {
            $validatedvalues = external_api::clean_returnvalue($this->function->returns_desc, $this->returns);
        } catch (Exception $ex) {
            $exception = $ex;
        }
 
        //PROCESS THE RESPONSE
        echo $response;
    }
 
    /**
     * Send the error information to the WS client
     * @param exception $ex the exception that we are sending
     */
    protected function send_error($ex=null) {
        //PROCESS THE ERROR MESSAGE
        echo $error;
    }
 
}

webservice/myprotocol/version.php

<?php
 
/**
 * Version details
 *
 * @package    webservice_myprotocol
 * @copyright  20XX Your Name
 * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 */
 
defined('MOODLE_INTERNAL') || die();
 
$plugin->version   = YYYYMMDDXX;        // The current plugin version (Date: YYYYMMDDXX)
$plugin->requires  = yyyymmddxx;        // Requires this Moodle version
$plugin->component = 'webservice_myprotocol'; // Full name of the plugin (used for diagnostics)