Web service API functions
Moodle 2.0
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 app will always retrieve the courses information first. Any function down in the workflow, only needs to return course ids, no need to return course fullname, shortname... The exertanl app should already knows it.
- 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 the issue. In most of the case, (s)he will be the person to validate the proposal.
4. link your new 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:
- always check capabilities and context
- write 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.
- do no set top level parameters as OPTIONAL => use DEFAULT for top level parameter
- errors should be handled as described in this document (work in progress)
- always indicate which file you read in core in order to code the web service function. Any web service functions match 100% the permissions and behaviors of Moodle core. 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.
- order of the functions: 1) xxx_params() 2) xxx() 3) xxx_returns()
You can now send your function for peer-review.
8. the integration priority follows these rules:
- the ones required for the official Mobile app (generally very few)
- the ones for which a git patch has been submitted.
- the most voted ones
- the other ones