Web services

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 with the option to plug in AMFPHP for Flash/Flex interfaces) as an API for those writing code to work against Moodle.

Please add new functions if there's functionality you want that isn't covered (we can refactor/whittle at the end).

The tracker bug for all this is here: MDL-12886

add user

[Feedback] Speaking as someone who will be using this API to integrate with another line of business application I would recommend the following changes.

The add_user method should really be a 'SetUser' ie it will create the record if it does not exist or update it it if it does. The ID that is passed into the method would be *our* primary key which Moodle would use to recognise the user record within Moodle. We would not normally need to know anything about the Moodle primary key.

One option to make the web services maintainable is to accept XML as a parameter and not a structure or custom object. That way you can define an XSD which will define required\optional parameters. Equally if you include a version number you can change the XML to add new features without having to redefine the web service signature itself (and hence clients will not have to recompile their code). So you may receive a SetUser call with XML V1.0 and another with XML V2.0 on the same webservice but from two different clients supporting different versions of the API.

The method *must* accept an array of users - it's a little trickier to set this up in the client code but is much more scalable (if there's some good sample code then this is easier anyway). The latency (round trip time) with web service calls is high so you want to do as much as you can in a single call. We have a customer who wants us to deploy Moodle to 40,000 users - we're not going to do that using individual calls.

Would it be possible to expand on the existing web service work rather than produce something completely new? We're investing a lot of effort with these services and we wouldn't like to have to re-do that work. [/Feedback]

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 ?). Also password should be "required" if authentication method is "internal" .

INPUT:

   firstname
   lastname
   email 
   idnumber
   login 
   authentication method (optional , default= manual ?)

OPERATION:

   Adds a new user to the user database 

OUTPUT:

   id or false

delete user

INPUT:

   idnumber  or 
   email or 
   id or
   login

OPERATION:

   User is marked as deleted
   All it's role assignments are destroyed 

OUTPUT:

   true/false

get user

INPUT:

   idnumber  or 
   email or 
   id or
   login

OPERATION:

   user record with optional fields set (Moodle 1.8 and later) and maybe some fields filtered out (password, 
   email if user said not to disclose it ...) depending of the identity of the "caller" (admin or the user himself) 

OUTPUT:

   false  or user record

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
   What about associated ressources, roles ... 

OUTPUT:

   true or false

get course

INPUT:

   id or  idnumber or shortname

OPERATION:

    fetch course record with some fields filtered out depending of the "caller" identity (admin, teacher, student ...)

OUTPUT:

   false  or course record

enrol student to course

[Feedback] It's not clear what the difference is or significance of ID vs. idnumber is. Remember the web service developers will probably not be users of Moodle so it needs to be clear. [/Feedback]

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

remove role from 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:

  remove given user's "standard" role from given course   

OUTPUT:

   true or false

get my courses

INPUT:

  user unique id (Moodle's ID or idnumber or login or email)

OPERATION:

  return a "list" of course's id in which given user move given user has some role assigned     

OUTPUT:

   "array" of (course id, course shortname, course fullname, role id, role name, course url)
   or false in case of error (bad user id)

get last changes in my courses

INPUT:

  user unique id (Moodle's ID or idnumber or login or email)
  course unique Id (Moodle's ID ,idnumber or shortname) - optional (default = all my courses)
  timestamp - optional (default = time of last connexion in every course)

OPERATION:

  return a "list" of changes (resource added/modified, new activities, etc.) for courses in which given user has some role assigned - since timestamp or last connexion in given course 

OUTPUT:

   "array" of (course id, course shortname, course fullname, role id, role name, url of the resource/activity, time of change)
   or false in case of error (bad user/course id)

get grades

INPUT:

  user unique id (Moodle's ID or idnumber or login or email)
  course unique Id (Moodle's ID ,idnumber or shortname) - optional (default = all my courses)
  

OPERATION:

  return a "list" of grades and statistics for the given student in the given course

OUTPUT:

   "array" of grades records (name,maxgrade,grade,percent,weight,weighted,sortOrder) 
   and "array" of stats (gradeItems,allgrades, points,totalpoints, percent, weight, weighted;)  
   or false in case of error (bad user/course id or user not in course)

get groups

OPERATION:

  return a "list" of group records in a given course (or site ?) 

get group members

OPERATION:

  return a "list" of ids  for members of a group (within a course or global) 

enrol to group

OPERATION:

  add a new member to a group

unenrol from group

OPERATION:

  remove membership from a group

get calendar events

OPERATION:

  return a "list" of event's identifiers suitable from the "get event" operation

get calendar event

OPERATION:

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

set calendar event

OPERATION:

  add/modify an event in Moodle database (site, course, private ...)