Latest revision as of 04:58, 27 November 2008

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

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.

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, AMFPHP, ...). Adding a new protocol support should be relatively easy.

How does it work

The web service client call a Moodle web service. The web service is located in a folder specific to the used protocol. It's usually a inout.php file. This file runs the web service server and gets the sent parameters. Then it calls a wrapper. The wrapper.php file is implemented in order to call the Moodle API which contains all callable functions. The wrapper will check a "generated file" in order to know which functions are available, and what their parameters and what they returned.
For any protocol there should be at least one inout.php file and one wrapper file.

Technical specs

The client calls the web service
The web service server receives the call
The web service server transforms the web service params into a common param format to all web service protocol => Format to be defined
The web service server calls a function call_moodle_function($functionname, $params)
call_moodle_function() checks through a WS API descriptor class that the params are legal for this function name
call_moodle_function() call the correct API moodle function
the call_moodle_function() return the result to the web service server
the web service server convert the result into a response

Params should include:

function parameter names, values and types
returned object fields (e.g. we cannot return a password field through a get_users function)
return value and type

Security

How are the web services secured ?
Security layer implemented by every protocol?

List of functions

All callable functions are declared into Moodle API, please read Moodle API documentation.

@@ Line 1: / Line 1: @@
-This page is to decide on a STANDARD list of CORE web service functions that we should support in Moodle (by XMLRPC, REST and SOAP) as an API for those writing code to work against Moodle.
+{{Template:Work in progress}}{{Moodle_2.0}}
-Please add new functions if there's functionality you want that isn't covered (we can refactor/whittle at the end).
+=Introduction=
+This page described the Web Services module implemented for Moodle 2.0<br>
+The tracker issue is here: MDL-12886<br>
+This module is been implemented by the [http://blogs.dfwikilabs.org/moodle_ws/ DFWS Team].
-==add user==
+=Implementation=
-I think we should require all data needed for a successful "first login" to Moodle without popping him out the profile page to fill in all missing required data. This may require extra inputs such as city, description ... (unsure of the full list depending of Moodle version ?).
+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, AMFPHP, ...). Adding a new protocol support should be relatively easy.
-Also password should be "required" if authentication method is "internal" .
-INPUT:
+== How does it work ==
-    firstname
+The web service client call a Moodle web service. The web service is located in a folder specific to the used protocol. It's usually a inout.php file. This file runs the web service server and gets the sent parameters. Then it calls a wrapper. The wrapper.php file is implemented in order to call the Moodle API which contains all callable functions. The wrapper will check a "generated file" in order to know which functions are available, and what their parameters and what they returned.<br>
-    lastname
+For any protocol there should be at least one inout.php file and one wrapper file.
-    email
-    idnumber
-    login
-    authentication method (optional , default= manual ?)
+== Technical specs ==
+# The client calls the web service
+# The web service server receives the call
+# The web service server transforms the web service params into a common param format to all web service protocol => Format to be defined
+# The web service server calls a function call_moodle_function($functionname, $params)
+# call_moodle_function() checks through a WS API descriptor class that the params are legal for this function name
+# call_moodle_function() call the correct API moodle function
+# the call_moodle_function() return the result to the web service server
+# the web service server convert the result into a response
-OPERATION:
+Params should include:
-    Adds a new user to the user database
+* function parameter names, values and types
+* returned object fields (e.g. we cannot return a password field through a get_users function)
+* return value and type
-OUTPUT:
+=Security=
-    id or false
+How are the web services secured ?<br>
+Security layer implemented by every protocol?
-==delete user==
+=List of functions=
-INPUT:
+All callable functions are declared into Moodle API, please read [https://docs.moodle.org/en/index.php?title=Development:Moodle_API Moodle API documentation].
-    idnumber  or
-    email or
-    id or
-    login
-OPERATION:
-    User is marked as deleted
-    All it's role assignments are destroyed
-OUTPUT:
-    true/false
-==add course==
-INPUT:
-    name
-    shortname
-    format (default topics)
-    idnumber
-OPERATION:
-    Adds a new course to the course table
-OUTPUT:
-    id or false
-==delete course==
-INPUT:
-    name OR
-    shortname  OR
-    idnumber OR
-    id
-OPERATION:
-    Deletes a course from the course table
-OUTPUT:
-    true or false
-==enrol student to course==
-INPUT:
-    course unique Id (Moodle's ID or idnumber or shortname)
-    student unique id (Moodle's ID or idnumber or login or email)
-OPERATION:
-    Assign student role to course
-OUTPUT:
-    true or false
-==unenrol student from course==
-INPUT:
-    course unique Id (Moodle's ID or idnumber or shortname)
-    student unique id (Moodle's ID or idnumber or login or email)
-OPERATION:
-    remove student role from course
-OUTPUT:
-    true or false
-==assign role to course
-INPUT:
-   course unique Id (Moodle's ID or idnumber or shortname)
-   user unique id (Moodle's ID or idnumber or login or email)
-   role id (teacher, non editing teacher, student (?) ...)
-OPERATION:
-   assign given user a "standard" role to given course
-OUTPUT:
-    true or false

Documentation

Development:Web services: Difference between revisions