Development:Moodle API

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

Introduction

This document is about the Moodle API introduced in Moodle 2.0. In order to be available more widely, Moodle 2.0 relocate core functions into different api.php files, called Moodle API.
Thus, the new web services module will be able to provide all of these functions as services. Moreover it would centralize core function into known location reducing code redundancy, bugs and maintenance time. With the time going, more of the core functions should end up into Moodle API.

Implementation

Create a new API file

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 (get(), update(), create(), delete(), ...).

Standard function: In order to manipulate object, we recommand to use:

   get() //for retrieving an object
   set() //for updating or creating an object
   update() //for updating an object, throws an exception if the object doesn't exist
   create() //for creating an object, throws an exception if the object (primary key) already exist
   delete() //for deleting an object, TO BE DEFINED: throws an exception if the object doesn't exist 

Need to define the API functions

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::update
   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.