Development:Moodle API

Note: This article is a work in progress. Please use the page comments for any recommendations/suggestions for improvement.

Moodle 2.0

Introduction

This document is about the Moodle API introduced in Moodle 2.0, which is intended to standardise and streamline methods for calling common control functions in Moodle core and modules. This is most useful for web services (where external systems want to control Moodle) but also for alternative interfaces such as Flex and so on.

To do this, Moodle 2.0 relocates important functions into new api.php files within each module, with standard documentation and structure to help reduce code redundancy and maintenance, while improving readability and functionality.

Over time we expect more and more Moodle functionality to move into these files.

Related documents

• Web Services for Moodle 2.0
• TO BE DONE: create a tracker issue for Moodle API with subtasks for every api.php file

Implementation

Convention

A new api.php file should be created into each module/block folder, and also the current admin/user/course/... common moodle folders.
This file should contains a class named from the module:

   class mod_forum_api
   class user_api
   class course_api
   ...

Into this class, static function will provide requested information and operation:

   create_forum()
   get_user()
   get_content()
   get_discussions()
   ...

Standard function names

In order to manipulate object and to be consistent for all API, we recommend to use: get_xxx() //for retrieving one or more objects named xxx set_xxx() //for updating or creating one or more object xxx update_xxx() //for updating one or more xxx objects, throws an exception if the object doesn't exist create_xxx() //for creating an object, throws an exception if the object (primary key) already exist delete_xxx() //for deleting an object, TO BE DEFINED: throws an exception if the object doesn't exist

API functions must be defined/declared

The web services module needs to know what parameter are required and what information are returned. So we need a way to generate all these information.
TO BE DEFINED: have a look at PHPdoc if we can generate all needed information from the documentation. Then we cache it in a file. The web services module will look at this file in order to create a WSDL file for soap, in order to know what function are available in REST,...

Call the API functions

These functions are called inside Moodle by the modules, block and others plugin, and also web services module. As they are static function, they should be called as:

   mod_forum_api::get_discussions
   user_api::create_users
   course_api::get_course
   ...

Functions List

All following paragraph matches a Moodle folder. All described functions should be included in a class named from the folder path, into an api.php file.

admin

These API would be used in order to configurate Moodle. ...

///config values set_admin_config($configs) //$configs is array("config" => array("value","description","code")) get_admin_config($code) get_admin_configs()

///Plugins > Activities get_activity_module_config(...) set_activity_module_config(...) get_activity_modules(...)

///Plugins > Block ...

///Plugins > Filter ...

///Plugins > Portfolio ...

///Plugins > Repository get_repository_plugins(...) add_repository_plugins(...) remove_repository_plugins(...) get_repository_plugin_config(...) set_repository_plugin_config(...) get_repository_instances(...) add_repository_instances(...) remove_repository_instances(...) get_repository_instance_config(...) set_repository_instance_config(...)

///Security get_security_config($pagename=) //return array("pagename" => array("config"=>"value"))

                                 //usefull if you want retrieve all config in once for only for security

///Server get_environment($version=null) get_server_config($pagename=) //return array("pagename" => array("config"=>"value"))

...

blog

get_blog_entries($userid, $startdate, $enddate, $number) create_blog_entries($userid, $entries) //array of entry array delete_blog_entries($entryids) update_blog_entry($entry) get_blog_user_preferences($userid) //return array of config (array("configname","value")) set_blog_user_preferences($userid, $configs)

calendar

create_calendar_events(...) delete_calendar_events(...) get_calendar_events(...) //return in an "exportable" format (iCal, vCal ...)an event recorded in Moodle database (site, course, private ...)

course

create_courses($arrayCourses) create_course_enrolments($role,$criteria_course,$course,$criteria_user,$users) delete_courses($criteria, $arrayCourses) delete_course_enrolments($role,$criteria_course,$course,$criteria_user,$users) get_courses($criteria, $arraySearch) get_course_enrolments($criteria_user,$user) get_courses_recent_activities($criteria, $arrayCourses)

grade

get_grades(...)

group

add_group_members($criteriaCourse, $course, $criteriaUser, $arrayUsers, $groupname) create_groups($criteria, $course, $groupnames) delete_groups($criteria, $course, $groupnames) get_groups($criteria, $course) get_groups_by_course($courseid) get_group_members($criteria, $course, $groupname) remove_group_members($criteriaCourse, $course, $criteriaUser, $arrayUsers, $groupname) set_group(...) update_group(...)

repository

///function to let teacher and user manage their repositories get_repository_instances($repository_type=null, $userid=null, $courseid=null) //if courseid!=null, get course level instances, else if userid != null get user level instances add_repository_instances($repositoryinstances) remove_repository_instances($repositoryinstances) get_repository_instance_config($repositoryinstanceid) set_repository_instance_config($repositoryinstanceid,$configs)

search

search($string);

user

create_users($users) //$users is an array of $user

                               //$user is an array(username, password, forcechangepwd, firstname, 
                               //                  lastname, email, emaildisplay, emailactivated,
                               //                  city, country, timezone, language, description,...)

delete_users($criteria, $users) get_users($criteria, $users) set_user($user) //$user is an array(...) update_user($user) //$user is an array(...)