Web services

1. REDIRECT [1]

Moodle 2.0

Introduction

This page describes the Web Services implementation that was added to Moodle 2.0 and is being extended with every subsequent version.

We support multiple web service protocols (REST, SOAP, XML-RPC and AMF). If that's not enough, support for new protocols can be added easily.

How it works

This simple example will give you an idea of how our web services infrastructure works. See External services security for more details.

1. The client sends a username and password to the web service protocol server script.
2. The protocol server returns a session token for that user account (how this is sent depends on the protocol).
3. The client calls a particular web service function including the session token.
4. The protocol server uses the token to check that the web service session is still active.
5. The protocol server call the matching external function, located in a externallib.php file inside the relevant module.
6. The external function checks that the current user has_capability to do this operation.
7. The external function calls the matching Moodle core function (in lib.php usually).
8. The core function can return a result to the external function.
9. The external function will return a result to the protocol server.
10. The protocol server returns the result to the client.

Web description format

All functions that can be called via web services are declared in a db/service.php file and can be defined in an externallib.php file somewhere. The classes we use to define these functions are explained in the External Service description document.

Web services functions

Every Moodle site can provide you with a page listing all function descriptions, with useful advice for any supported protocol.

At the moment the only way to get the full Moodle web service documentation is:

1. login as admin
2. enable ws documentation into Admin block > Web service > Manage Protocol
3. create a service and add all Moodle functions to it
4. give create_token capability to a none admin user
5. login as this user
6. access your Security Keys page and click on the documentation.

An issue has been created to make it a lot easier: MDL-28650

However, here is a list of the functions available in Moodle 2.1:

user:

• create_users()
• delete_users()
• update_users()
• get_users_by_id() - returns a list of full user objects specified by user ids (only useful for site admin accounts)
• get_course_participants_by_id() - returns a list of full user objects in specific courses (that you can see)
• get_users_by_courseid() - returns some subset of full user objects from a course (perhaps by group or capability)

course:

• get_courses()
• create_courses()

group:

• create_groups()
• get_groups()
• get_course_groups()
• delete_groups()
• get_groupmembers()
• add_groupmembers()
• delete_groupmembers()

enrol:

• get_enrolled_users() - get some minimal information about the users enrolled in a course (DEPRECATED)
• get_users_courses() - get list of course ids that a user is enrolled in (if you are allowed to see that)
• role_assign()
• role_unassign()

enrol/manual:

• manual_enrol_users()

webservice:

• get_siteinfo_parameters()

message:

• send_instantmessages()

files:

• get_files()
• upload()

Authentication

Please have a look to the External services security page

See also

• The official discussion forum is here
• The tracker issues are here: MDL-12886 and MDL-17135
• External services security
• External services description
• Creating a web service and a web service function
• Creating a web service client
• Web_Services