MoodleDocs - User contributions [en]

Talk:Web services

2008-01-03T13:35:17Z

Saint-georges: /* output of operations: adding URLs? */

==general remarks about OUTPUT of operations:==
Is true of false informative enough ?
Should the API have some sort of "last_error" function giving back more details such as "non existing course, non existing user, duplicate entry ...)
Shall we consider that affecting a role that already exist or removing role that do not exist as an error (output=false) or not (output=true)
:yep, agree, I'd result always one well defined $result object, with his status, error code and error msg (and perhaps, the whole original WS request encapsulated for easier debugging).
:[[User:Eloy Lafuente (stronk7)|Eloy Lafuente (stronk7)]] 19:55, 21 December 2007 (CST)
I agree but throught the WS we need to be be carefull with the feedback we give to errors, due to security issues. --[[User:Ludo (Marc Alier)|Ludo (Marc Alier)]] 14:14, 22 December 2007 (CST)

==some WS to be able to... build courses ?==
Perhpas it would be a great idea to start thinking about some WS functionalities like this:

* add_course, delete_course, reset_course
* add_section, delete_section, show_section, hide_section
* add_activity, delete_activity, show_activity, hide_activity

Apart from the WS utility itself: automated creation of courses... it would help (or force, as we prefer), to better encapsulate course/section/modules internals, 100% isolating the creation and configuration from the frontend (forms, WS...). It implies some decisions, like upwards compatibility of old modules (although I think it can be maintained)... and so on, you know.

Just one idea to analyse. But with benefits in the end, IMO.
[[User:Eloy Lafuente (stronk7)|Eloy Lafuente (stronk7)]] 20:02, 21 December 2007 (CST)

I do agree with this ; this would also allow creation of specific courses, customized for some users, depending of their "performances" in external evaluations methods ; when the ePortfolio API will be finalized in Moodle core's, accessing the portfolio of any user would be needed.
[[User:Patrick Pollet|Patrick Pollet]] 04:21, 30 December 2007 (CST)

==the problem of ID of entity to fetch:==
In the list of API calls defined in this page, Moodle entity to process (user,course,grade,event ...) is identified by an ID, that is implicitly the Moodle's internal id field used in the database. This raises a problem since it is very likely that in the "external SIS" talking to Moodle across the Web Service, the entity will be identified by another attribute such as an idNumber (user,course), a short name (course) or even an username (login of user).

So either we must provide :

* extra API calls to convert external identifiers to Moodle's internal id, such as user_id_from_idnumber, user_id_from_username, course_id_from_shortname ..., at the cost of extra calls before the real one ; three calls would be needed to enrol student "CS2121212", to course "JAVA_101".

* extra API functions such as delete_user_byusername, get_course_by_idnumber , enrol_student_byidnumber_tocourse_byshortname ....

* or add parameters to the current API calls specifiying what identifier we are using such as delete_user(id,idField) with idField being a string that could be "id","idnumber","username","email" ... or enrol_student(sid,"idnumber",cid,"shortname") . This is the approach in the current SOAP implementation (with some calls of the previous type (get_user_byusername()...)

[[User:Patrick Pollet|Patrick Pollet]] 04:21, 30 December 2007 (CST)

== output of operations: adding URLs?==
In addition, I suggest to return the full URL towards every Moodle entity, either added or got.
* user added with id 12345 --> http://moodle.xxx.edu/user/view.php?id=12345&course=1
* got user 12345 --> http://moodle.xxx.edu/user/view.php?id=12345&course=1
* course added with id 67 --> http://moodle.xxx.edu/course/view.php?id=67
* got course 67 --> http://moodle.xxx.edu/course/view.php?id=67
* etc.

Today, in my uPortal installation, I request for Moodle database and display a list of courses in which the connected user is enrolled. Of course I provide links to these courses so that he can directly access. In addition I display a list of the last changes in these courses, again with links to the resources/activities.

If the URLs are returned by the WS then the calling service has nothing to know about Moodle URLs. Else it has to build every URL by aggregating Moodle alias + adequate PHP script + entity ID

Talk:Web services

2008-01-03T10:57:56Z

Saint-georges:

==general remarks about OUTPUT of operations:==
Is true of false informative enough ?
Should the API have some sort of "last_error" function giving back more details such as "non existing course, non existing user, duplicate entry ...)
Shall we consider that affecting a role that already exist or removing role that do not exist as an error (output=false) or not (output=true)
:yep, agree, I'd result always one well defined $result object, with his status, error code and error msg (and perhaps, the whole original WS request encapsulated for easier debugging).
:[[User:Eloy Lafuente (stronk7)|Eloy Lafuente (stronk7)]] 19:55, 21 December 2007 (CST)
I agree but throught the WS we need to be be carefull with the feedback we give to errors, due to security issues. --[[User:Ludo (Marc Alier)|Ludo (Marc Alier)]] 14:14, 22 December 2007 (CST)

==some WS to be able to... build courses ?==
Perhpas it would be a great idea to start thinking about some WS functionalities like this:

* add_course, delete_course, reset_course
* add_section, delete_section, show_section, hide_section
* add_activity, delete_activity, show_activity, hide_activity

Apart from the WS utility itself: automated creation of courses... it would help (or force, as we prefer), to better encapsulate course/section/modules internals, 100% isolating the creation and configuration from the frontend (forms, WS...). It implies some decisions, like upwards compatibility of old modules (although I think it can be maintained)... and so on, you know.

Just one idea to analyse. But with benefits in the end, IMO.
[[User:Eloy Lafuente (stronk7)|Eloy Lafuente (stronk7)]] 20:02, 21 December 2007 (CST)

I do agree with this ; this would also allow creation of specific courses, customized for some users, depending of their "performances" in external evaluations methods ; when the ePortfolio API will be finalized in Moodle core's, accessing the portfolio of any user would be needed.
[[User:Patrick Pollet|Patrick Pollet]] 04:21, 30 December 2007 (CST)

==the problem of ID of entity to fetch:==
In the list of API calls defined in this page, Moodle entity to process (user,course,grade,event ...) is identified by an ID, that is implicitly the Moodle's internal id field used in the database. This raises a problem since it is very likely that in the "external SIS" talking to Moodle across the Web Service, the entity will be identified by another attribute such as an idNumber (user,course), a short name (course) or even an username (login of user).

So either we must provide :

* extra API calls to convert external identifiers to Moodle's internal id, such as user_id_from_idnumber, user_id_from_username, course_id_from_shortname ..., at the cost of extra calls before the real one ; three calls would be needed to enrol student "CS2121212", to course "JAVA_101".

* extra API functions such as delete_user_byusername, get_course_by_idnumber , enrol_student_byidnumber_tocourse_byshortname ....

* or add parameters to the current API calls specifiying what identifier we are using such as delete_user(id,idField) with idField being a string that could be "id","idnumber","username","email" ... or enrol_student(sid,"idnumber",cid,"shortname") . This is the approach in the current SOAP implementation (with some calls of the previous type (get_user_byusername()...)

[[User:Patrick Pollet|Patrick Pollet]] 04:21, 30 December 2007 (CST)

== output of operations: adding URLs?==
In addition, I suggest to return the full URL towards every Moodle entity, either added or got.
* user added with id 12345 --> http://moodle.xxx.edu/user/view.php?id=12345&course=1
* got user 12345 --> http://moodle.xxx.edu/user/view.php?id=12345&course=1
* course added with id 67 --> http://moodle.xxx.edu/course/view.php?id=67
* got course 67 --> http://moodle.xxx.edu/course/view.php?id=67
* etc.

Today, in my uPortal installation, I request for Moodle database and display a list of courses in which the connected user is enrolled. Of course I provide links to these courses so that he can directly access. In addition I display a list of the last changes in these courses, again with links to the resources/activities.

If the URLs are returned by the WS then the calling service has not to know about Moodle URLs. Else it has to build every URL by aggregating Moodle alias + adequate PHP script + entity ID

Web services

2007-12-20T16:16:57Z

Saint-georges: /* get last changes in my courses */

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.

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

==add user==
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

==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

==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

==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 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)

Web services

2007-12-20T16:15:15Z

Saint-georges: /* get my courses */

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.

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

==add user==
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

==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

==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

==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 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, role id, url of the resource/activity, time of change)
or false in case of error (bad user/course id)

Web services

2007-12-20T16:04:21Z

Saint-georges:

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.

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

==add user==
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

==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

==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

==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, role id, 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 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, role id, url of the resource/activity, time of change)
or false in case of error (bad user/course id)

Web services

2007-12-20T16:01:42Z

Saint-georges:

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.

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

==add user==
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

==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

==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

==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, role id)
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 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, role id, url of the resource/activity, time of change)
or false in case of error (bad user/course id)