Web service API functions

Moodle 2.0

Color meaning

Implemented

Must be implemented

Suggested

Web service protocols

Name	Moodle Ver.	Description	Issue
AMF	2.0	Adobe protocol to communicate with Flash/Flex apps
REST (returning XML)	2.0	XML data accessed through a REST API (not restful)
REST (returning JSON)	2.X	JSON data accessed through a REST API (not restful)	MDL-29242
REST (returning JSONP)	2.X	Would be very useful for client-side JavaScript
JSON	2.2	JSON server receives a JSON encoded params and return JSON encoded values.	MDL-21341
SOAP	2.0	Very important for interoperating with Java and .Net applications. There was a partial implementation JAVA/.Net in Moodle 2.0, but it does not work for anything but the most trivial functions. It is fully working with PHP clients.	MDL-20804, MDL-28988, MDL-28989
XMLRPC	2.0	XML remote-procedure call.

Web service functions

Naming convention

We updated (regularised) the naming convention in Moodle 2.2. See MDL-29106 for those details.

All functions should be named as follows:

• wsfunction = fullcomponent_methodname
• fullcomponent = frankenstyle (eg core_xxxx or mod_xxx etc)
• methodname = verb_noun(s)
• verb = get|create|delete|update
• noun = moodle objects, usually plural (eg posts, discussions, users, courses etc)

API Roadmap

Tracker issue: MDL-29934

Area	Moodle 2.2 name	Moodle 2.0/2.1 name	Introduced in	Description	Issue
user	core_user_create_users()	moodle_user_create_users()	2.0	Create users - admin function
user	core_user_delete_users()	moodle_user_delete_users()	2.0	Delete users - admin function
user	core_user_update_users()	moodle_user_update_users()	2.0	Update users
user	core_user_get_users_by_id()	moodle_user_get_users_by_id()	2.0	Get users by id
user	core_user_get_course_user_profiles()	moodle_user_get_course_participants_by_id()	2.1	Get course user profiles by id
user	core_user_get_users()		2.X	Get users from a specifed key/value	MDL-29938
user	core_user_get_completed_users_per_course()		2.X	Get users who completed the course	MDL-28320
user	core_user_get_completed_courses_per_user()		2.X	Get courses that a user completed	MDL-28319
course	core_course_get_courses()	moodle_course_get_courses()	2.0	Return course details
course	core_course_create_courses()	moodle_course_create_courses()	2.0	Create new courses
course	core_course_update_courses()		2.X	including moving categories	MDL-30062
course	core_course_delete_courses()		2.X		MDL-13130
course	core_course_get_contents()		2.2	including sections, activities etc	MDL-28646
course	core_course_get_recent_activity()		2.X	also works for site course	MDL-13135
group	core_group_create_groups()	moodle_group_create_groups()	2.0	Creates new groups
group	core_group_get_groups()	moodle_group_get_groups()	2.0	Returns group details.
group	core_group_get_course_groups()	moodle_group_get_course_groups()	2.0	Returns all groups in specified course
group	core_group_delete_groups()	moodle_group_delete_groups()	2.0	Deletes all specified groups
group	core_group_get_group_members()	moodle_group_get_groupmembers()	2.0	Returns group members
group	core_group_add_group_members()	moodle_group_add_groupmembers()	2.0	Adds group members
group	core_group_delete_group_members()	moodle_group_delete_groupmembers()	2.0	Deletes group members
role	core_role_assign_roles()	moodle_role_assign()	2.0	Manual role assignments
role	core_role_unassign_roles()	moodle_role_unassign()	2.0	Manual role unassignments
enrol	NONE	moodle_enrol_get_enrolled_users()	2.0	get some minimal information about the users enrolled in a course (DEPRECATED)
enrol	core_enrol_get_enrolled_users()	moodle_user_get_users_by_courseid()	2.1	Get enrolled users by course id
enrol	core_enrol_get_users_courses()	moodle_enrol_get_users_courses()	2.0	get list of course ids that a user is enrolled in (if you are allowed to see that)
enrol/manual	enrol_manual_enrol_users()	moodle_enrol_manual_enrol_users()	2.0	Manual enrol users
enrol/manual	enrol_manual_unenrol_users()		2.X	Manual unenrol users	MDL-30063
enrol/manual	enrol_ manual_update_enrolments()		2.X		MDL-30064
enrol/cohort	enrol_cohort_create()		2.X		MDL-29472
enrol/cohort	enrol_cohort_delete()		2.X		MDL-29935
enrol/cohort	enrol_cohort_update()		2.X		MDL-29936
enrol/cohort	enrol_cohort_remove_user()		2.X		MDL-29939
enrol/cohort	enrol_cohort_add_user()		2.X		MDL-29473
enrol/self	enrol_self_enrol()		2.X		MDL-30065
enrol/self	enrol_self_unenrol()		2.X		MDL-30066
webservice	core_webservice_get_site_info()	moodle_webservice_get_siteinfo()	2.1	Return some site info / user info / list web service functions
message	core_message_send_instant_messages()	moodle_message_send_instantmessages()	2.1	Send instant messages
message	core_message_get_instant_messages()		2.X	params for unread etc	MDL-30068
message	core_message_create_contacts()		2.X		MDL-30070
message	core_message_delete_contacts()		2.X		MDL-30071
notes	core_notes_create_notes()	moodle_notes_create_notes()	2.1	Create notes
notes	core_notes_delete_notes()		2.X		MDL-30072
events	core_event_trigger_event()		2.X	triggers an event	MDL-30073
calendar	core_calendar_create_calendar_events()		2.X		MDL-30074
calendar	core_calendar_update_calendar_events()		2.X		MDL-30075
calendar	core_calendar_delete_calendar_events()		2.X		MDL-30076
files	core_files_get_files()	moodle_file_get_files()	2.0	browse moodle files
files	core_files_upload()	moodle_file_upload()	2.0	upload a file to moodle (DEPRECATED)
files	core_files_create_files()		2.X	can also do folders via a flag	MDL-30077
files	core_files_update_files()		2.X		MDL-30078
files	core_files_delete_files()		2.X		MDL-30079
category	core_course_create_categories()		2.X		MDL-30081
category	core_course_delete_categories()		2.X		MDL-30082
category	core_course_update_categories()		2.X		MDL-30083
category	core_course_get_categories()		2.X		MDL-30084
grade	core_grade_get_grades()		2.X	for user, course, activity etc	MDL-30085
grade	core_grade_get_scales()		2.X		MDL-30086
grade	core_grade_get_outcomes()		2.X		MDL-30087
grade	core_grade_update_grades()		2.X	including feedback	MDL-30088
grade	core_grade_create_grades()		2.X		MDL-30089
ratings	core_rating_get_ratings()		2.X		MDL-30090
ratings	core_rating_create_ratings()		2.X		MDL-30091
ratings	core_rating_update_ratings()		2.X		MDL-30092
ratings	core_rating_delete_ratings()		2.X		MDL-30093
comments	core_comment_get_comments()		2.X		MDL-30094
comments	core_comment_create_comments()		2.X		MDL-30095
comments	core_comment_update_comments()		2.X		MDL-30096
comments	core_comment_delete_comments()		2.X		MDL-30097
forum	mod_forum_get_forums()		2.X		MDL-30098
forum	mod_forum_create_forums()		2.X		MDL-30099
forum	mod_forum_update_forums()		2.X		MDL-30100
forum	mod_forum_delete_forums()		2.X		MDL-30101
forum	mod_forum_get_discussions()		2.X		MDL-30102
forum	mod_forum_create_discussions()		2.X		MDL-30103
forum	mod_forum_update_discussions()		2.X		MDL-30104
forum	mod_forum_delete_discussions()		2.X		MDL-30105
forum	mod_forum_get_posts()		2.X		MDL-30106
forum	mod_forum_create_posts()		2.X		MDL-30107
forum	mod_forum_update_posts()		2.X		MDL-30108
forum	mod_forum_delete_posts()		2.X		MDL-30109

How to contribute a web service function to core

1. before to create a new issue, check if one of the core functions in Moodle or a function from the roadmap already matches your need.

2. create an issue for your new web service function. The issue title should be the web service function name. The issue description should indicate the specs. Example:

This web service function will return assignements

Parameters:

---

array of course ids - Default: empty array array of capabilities - Default: empty array

Return value:

---

array of [

   struct{
       course struct [id, fullname, shortname, timemodified]
       array of assignment [id,name,timedue,grade,timemodified]
   }

]

Keep in mind:

• the web service function should not return more than the minimal. Sometimes ids are enough. We expect the client/external app to manage a local storage. For example, an external app will always retrieve the courses information first. Any function down in the app workflow, only needs to return course ids. The exertanl app should already knows course fullname, shortname...
• avoid functions that are just a part of more global functions. We don't need a set_this_field function when a generic update_object could do it. This is to avoid code duplication and long maintenance.
• Moodle contextids are internal to Moodle and are not sent to the external app. This is being discussed in this issue.

3. add the module maintainer as watcher on your issue. In most of the case, (s)he will be the person to validate the proposal.

4. link your issue to the roadmap. Your issue should appear in the "has been marked as being related by:" section.

5. once we all agree on the specs, the web service function is placed as subtask in the roadmap.

6. implement the function.

7. before sending your implementation for peer review check that:

• you checked capabilities and context
• you wrote a complete documentation into xxx_params() and xxx_return() external description functions. The generated API documentation will only show to client developers information from this two functions and in the services.php. You have to be exhaustive on how to use the function.
• you did no set top level parameters as OPTIONAL => use DEFAULT for top level parameter
• you handled errors as described in this document (work in progress)
• you ordered of the functions: 1) xxx_params() 2) xxx() 3) xxx_returns() (so the integrator is not being mark as last history commiter in git for the all functions)
• you commented in the tracker issue which file in core contains the permission/security checkings. Any web service function must match 100% the Moodle permissions and behaviors. You save the reviewer a lot of time to let him know which file you look at. Usually it's a form script + a page script.

You can now send your function for peer-review.

8. the integration priority follows these rules:

1. the web service functions required for the official Mobile app (generally very few)
2. the web service functions for which a git patch has been submitted.
3. the most voted ones
4. the other ones

See also

• Web services developer documentation
• Web services user documentation