Web service API functions: Difference between revisions
Line 22: | Line 22: | ||
| style="background:#D4FFDF;" | REST (returning XML) || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | XML data accessed through a REST API (not restful) || | | style="background:#D4FFDF;" | REST (returning XML) || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | XML data accessed through a REST API (not restful) || | ||
|- | |- | ||
| style="background:#D4FFDF;" | REST (returning JSON) || style="background:#D4FFDF;" | 2. | | style="background:#D4FFDF;" | REST (returning JSON) || style="background:#D4FFDF;" | 2.2 || style="background:#D4FFDF;" | JSON data accessed through a REST API (not restful) || MDL-29242 | ||
|- | |- | ||
| style="background:#ffdfcd;" | REST (returning JSONP) || style="background:#ffdfcd;" | 2.X || style="background:#ffdfcd;" | Would be very useful for client-side JavaScript || MDL-29913 | | style="background:#ffdfcd;" | REST (returning JSONP) || style="background:#ffdfcd;" | 2.X || style="background:#ffdfcd;" | Would be very useful for client-side JavaScript || MDL-29913 |
Revision as of 08:10, 9 March 2012
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.2 | 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:
- 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 issues; and then
- other web service functions.