Plugins/Auth/WebServices

Web Services support for Mahara

Artefact Webservices

Web Services plugin based support for Mahara.

The Web Services support is modelled on the webservices subsystem for Moodle and provides REST, XML-RPC, and SOAP alternatives for any registered function. The REST interface also supports JSON.

Installation Instructions

This requires the simple authentication module auth/webservice See https://gitorious.org/mahara-contrib/auth-webservice

To install you need to download both modules:

get https://gitorious.org/mahara-contrib/artefact-webservice/archive-tarball/master

and https://gitorious.org/mahara-contrib/auth-webservice/archive-tarball/master

Then do the following:

 cd /path/to/mahara/htdocs/auth
 tar -xzf /path/to/mahara-contrib-auth-webservice-master.tar.gz
 mv mahara-contrib-auth-webservice webservice
 cd /path/to/mahara/htdocs/artefact
 tar -xzf /path/to/mahara-contrib-artefact-webservice-master.tar.gz
 mv mahara-contrib-artefact-webservice webservice

You should now have the two necessary modules in place.

Now login as admin to Mahara, and go through the upgrade process to complete the install. In order to make the auth/webservice module available, you should add this as an authentication plugin for each Institution that requires access. Do this via the admin/users/institutions.php page.

Configuration

The configuration interface can be found under Site administration for plugins - http://mahara.local.net/artefact/webservice/pluginconfig.php

Read on for more configuration details.

Testing

The testing framework and examples are based on simpletest unit tests. These are all located in the artefact/webservice/simpletest directory. To run these, you must switch user permissions to the web server user account eg:

 # for a debian based install
 cd /path/to/artefact/webservice/simpletest
 sudo -u www-data php testwebservice.php

This will run the tests in testwebservice.php which covers all the webservice API functions in artefact/webservice/serviceplugins/(user|group) that make up the core function interfaces.

If you do not switch user permissions then the testing will likely fail as the process will not have write permissions to the Mahara data directory.

Developing Functions for Services

Developing functions follow a plugin architecture where the following locations are swept on upgrade for artefact/webservice:

• admin
• local
• api
• artefact/webservice

Within each of these module locations there is a check for a subdirectory serviceplugins. The serviceplugins directory is then checked for further web service plugin directories. If we take the example of user and group, which exist as standard plugins in the artefact/webservice module, then the following directories exist:

• artefact/webservice/serviceplugins/user
• artefact/webservice/serviceplugins/group

Each plugin must have two files service.php and externallib.php.

externallib.php

This contains the description of the function interfaces, and the function to be called. These descriptions are used to determine what valid parameters can be passed, and is the basis for the data type checking that is performed automatically for import, and export parameter values. The interface description is also used to for the automatic API documentation generation that can be viewed in the web services configuration.

 class mahara_group_external extends external_api {
   ...
   /**
    * Returns description of method parameters
    * @return external_function_parameters
    */
   public static function create_groups_parameters() {
  
       $group_types = group_get_grouptypes();
       return new external_function_parameters(
           array(
               'groups' => new external_multiple_structure(
                   new external_single_structure(
                       array(
                           'name'            => new external_value(PARAM_RAW, 'Group name'),
                           'shortname'       => new external_value(PARAM_RAW, 'Group shortname for API only controlled groups', VALUE_OPTIONAL),
                           'description'     => new external_value(PARAM_NOTAGS, 'Group description'),
                           'institution'     => new external_value(PARAM_TEXT, 'Mahara institution - required for API controlled groups', VALUE_OPTIONAL),
                           'grouptype'       => new external_value(PARAM_ALPHANUMEXT, 'Group type: '.implode(',', $group_types)),
                           'jointype'        => new external_value(PARAM_ALPHANUMEXT, 'Join type - these are specific to group type - the complete set are: open, invite, request or controlled', VALUE_DEFAULT, 'controlled'),
                           'category'        => new external_value(PARAM_TEXT, 'Group category - the title of an existing group category'),
                           'public'          => new external_value(PARAM_INTEGER, 'Boolean 1/0 public group', VALUE_DEFAULT, '0'),
                           'usersautoadded'  => new external_value(PARAM_INTEGER, 'Boolean 1/0 for auto-adding users', VALUE_DEFAULT, '0'),
                           'members'         => new external_multiple_structure(
                                                           new external_single_structure(
                                                               array(
                                                                   'id' => new external_value(PARAM_NUMBER, 'member user Id', VALUE_OPTIONAL),
                                                                   'username' => new external_value(PARAM_RAW, 'member username', VALUE_OPTIONAL),
                                                                   'role' => new external_value(PARAM_ALPHANUMEXT, 'member role: admin, ')
                                                               ), 'Group membership')
                                                       ),
                           )
                   )
               )
           )
       );
   }
  
   /**
    * Create one or more group
    *
    * @param array $groups  An array of groups to create.
    * @return array An array of arrays
    */
   public static function create_groups($groups) {
       global $USER, $WEBSERVICE_INSTITUTION;
  
       // Do basic automatic PARAM checks on incoming data, using params description
       $params = self::validate_parameters(self::create_groups_parameters(), array('groups'=>$groups));
       ...
    
       return $groupids;
   }
   
  /**
    * Returns description of method result value
    * @return external_description
    */
   public static function create_groups_returns() {
       return new external_multiple_structure(
           new external_single_structure(
               array(
                   'id'       => new external_value(PARAM_INT, 'group id'),
                   'name'     => new external_value(PARAM_RAW, 'group name'),
               )
           )
       );
   }
 ...
 }

service.php

This contains the description of functions to be added to the external_functions table, and gives the module author an opportunity to load up basic service groups for external_services.

 $functions = array(
  ...
     'mahara_group_create_groups' => array(
         'classname'   => 'mahara_group_external',
         'methodname'  => 'create_groups',
         'classpath'   => 'artefact/webservice/serviceplugins/group',
         'description' => 'Create groups',
         'type'        => 'write',
     ),
  ...
 );
 
 $services = array(
  ...
         'Simple Group Provisioning' => array(
                 'functions' => array ('mahara_group_create_groups', ... ),
                 'enabled'=>1,
                 'restrictedusers'=>1,
         ),
  ...
 );

Core Function Interfaces

The base set of APIs are implmented in artefact/webservice/serviceplugins/.

These cover User, Favourite, and Group administration functions.