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	MDL-29913
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)

Core web service functions

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
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
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
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
notes	core_notes_create_notes()	moodle_notes_create_notes()	2.1	Create notes
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)

API Roadmap

Tracker issue: MDL-29934

How to contribute a web service function to core

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

2. Create a new feature issue in the tracker for your new web service function. The issue title should be the web service function name, and the issue description should indicate the specs. The following is an example.

This web service function will return assignments:

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 the following in mind.

• The web service API is designed to be a clean set of functions with very little overlap. Each web service function should return minimal required information - sometimes ids are enough. We expect the client/external app to manage some local storage between calls. For example, an external app will always retrieve the courses information first. Any function down the app workflow, only needs to return course ids. The external app should already know course fullname, shortname...
• Avoid functions that are too specific - look for the most general possible case. For example, 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-term maintenance.
• Moodle contextids are generally internal to Moodle and are not used in the API. (This is being discussed in this issue).

3. Add the module maintainer as watcher on your issue. In most of the case, they will be the person to validate the proposal.

4. Link your issue to the Web service API Roadmap. Your issue should appear in the "has been marked as being related by:" section.

5. Once you, the component leader and Jerome Mouneyrac (the WS maintainer) all agree on the specs for a web service function, the web service function is placed as a subtask in the roadmap.

6. Implement the function according to the specs.

7. Check that you have:

• checked capabilities and context
• written complete documentation in the xxx_params() and xxx_return() external description functions. The generated API documentation will only show to client developers information from these two functions and in the services.php file. Be concise about how to use the function.
• set top level parameters as DEFAULT (don't use OPTIONAL)
• handled errors as described in this document (work in progress)
• ordered the functions: 1) xxx_params() 2) xxx() 3) xxx_returns() (so the integrator is not marked as the last history committer in Git for the functions)
• commented in the tracker issue about which file in core contains the permission/security checkings. All web service functions must correspond 100% with Moodle permissions and behaviours. You will save reviewers a lot of time by letting them know which file to look at. Usually it's a form script + a page script.
• DB write functions need to support transactions ($transaction = $DB->start_delegated_transaction(); / $transaction->allow_commit();)

8. You can now send your function for peer-review.

9. 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 highly voted issues; and then
4. other contributions.

See also

• Web services developer documentation
• Web services user documentation