Web service API functions
From MoodleDocs
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 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 an issue for your new web service function. The issue title should be the web service function name, and the issue description should indicate the specs. 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 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 in the app workflow, only needs to return course ids. The external app should already knows 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 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 subtask in the roadmap.
6. Implement the function according to the specs.
7. Check that you have:
- checked capabilities and context
- wrote complete documentation in the 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.
- set top level parameters as DEFAULT (don't use OPTIONAL)
- handled errors as described in this document (work in progress)
- 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)
- 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 behaviors. You will save reviewers a lot of time by letting him know which file to look at. Usually it's a form script + a page script.
- if a DB Write function fails during its process, then the function need to support transaction ($transaction = $DB->start_delegated_transaction(); / $transaction->allow_commit();)
8. You can now send your function for peer-review.
9. The integration priority follows these rules:
- the web service functions required for the official Mobile app (generally very few)
- the web service functions for which a git patch has been submitted.
- the most voted ones
- other ones
