Introduction
This article provides instructions on how to configure Moodle to use web services and REST API for four (4) core most commonly used web services with response examples in JSON and XML.
These web services are used when integrating two or more different systems through users and enrollments to courses. Web services is one means of integration, which requires development on the primary application to call Moodle web services. For custom web services or consulting please call sales line for a quote.
The article has been split into different sections to make it easier to follow along.
Sections/Summary of the Steps
Please note the following Sections/Steps.
How to Add Web Services:
Below are the step by step instructions for adding web services.
Using Custom web services: You can install custom web services by copying your web service plugins to the local folder on FTP.
- Enable Web services: Ensure that web service is enabled under Advanced Features so that you can use them. Do it from Site Administration > Advanced features > Enable Web Services > Checkbox On.
- Create an External Service: Go to Site Administration > Plugins > Web Services > External Services. Click on 'Add' under Custom Services header. On page 'External Service' form. Enter a name in the name textbox for your web service. Select Enable and Authorized checkboxes (if the webservice is only for authorized users). There are other options you can use if you want to.Click the Add Service button to add your service. Doing that will redirect you to Add Functions page.
- Add Functions to Your Created web service: Click Add Functions > Select All the Core functions (or the ones that you need) > Click Add Functions Button.
- Enable Protocols: Go to Site Administration > Plugins > Web Services > Manage protocols page and/or enable REST protocol and XML-RPC protocol based on your need.
- Manage Tokens: Go to Site Administration > Plugins > Web services > Manage Tokens > Add. Specify username/id, i.e. the user, who will use the token. From the dropdown option named service, select your web service name you have just created in steps 3 and 4. You can optionally set IP Restriction and Token Validity date here as well. Press save changes.
API Reference
This API reference is organized by resource type. Each resource type has one or more methods.
Resource types
- Users
1.1. core_user_create_users
1.2. core_user_get_users_by_field
1.3. core_user_update_users
- Enrolments
2.1. enrol_manual_enrol_users
1.1 Users: core_user_create_users
Create users.
Request
HTTP request
POST http://localhost/moodle/webservice/rest/server.php |
||
Property name | Value | Description |
Required properties | ||
wstoken | string | Valid Moodle token |
wsfunction | core_user_create_users | Function name |
Optional properties | ||
moodlewsrestformat | json | parameter to allow JSON output |
Parameters
Property name | Value | Description |
Required properties | ||
users[0][username] | string | Username policy is defined in Moodle security config |
users[0][password] | string | Plain text password consisting of any characters |
users[0][firstname] | string | The first name(s) of the user |
users[0][lastname] | string | The family name of the user |
users[0][email] | string | A valid and unique email address |
Optional properties | ||
users[0][auth] | string | Default to "manual" Auth plugins include manual, ldap, imap, etc |
users[0][idnumber] | string | Default to "" An arbitrary ID code number perhaps from the institution |
users[0][lang] | string | Default to "en". Language code such as "en", must exist on server |
users[0][theme] | string | Theme name such as "standard", must exist on server |
users[0][timezone] | string | Timezone code such as Australia/Perth, or 99 for default |
users[0][mailformat] | int | Mail format code is 0 for plain text, 1 for HTML etc |
users[0][description] | string | User profile description, no HTML |
users[0][city] | string | Home city of the user |
users[0][country] | string | Home country code of the user, such as AU or CZ |
users[0][firstnamephonetic] | string | The first name(s) phonetically of the user |
users[0][lastnamephonetic] | string | The family name phonetically of the user |
users[0][middlename] | string | The middle name of the user |
users[0][alternatename] | string | The alternate name of the user |
Working Example
http://yourmoodle.org/webservice/rest/server.php?wstoken=ce4d384c0c008b69fb409258cec722ba&moodlewsrestformat=json&wsfunction=core_user_create_users&users[0][username]=923116&users[0][email]=you@yourhost.org&users[0][lastname]=Test1&users[0][idnumber]=923116&users[0][firstname]=Moodle&users[0][password]=P@40ssword123!
NOTE: use your Moodle site URL instead of yourmoodle.org and your generated token instead of ce4d384c0c008b69fb409258cec722ba
Response
XML
PostData Example:
$token = 'ce4d384c0c008b69fb409258cec722ba'; $randval = mt_rand(999, 9999999); $userdata[] = array( 'username' => 'testws' . $randval, 'firstname' => 'testws', 'lastname' => $randval, 'password' => 'Testws.' . $randval, 'email' => 'testws+' . $randval . '@example.com', 'city' => 'Vancouver', 'country' => 'CA', 'idnumber' => $randval );
$postdata = array( 'wstoken' => $token, 'wsfunction' => 'core_user_create_users', 'users' => $userdata ); |
Response Example:
<?xml version="1.0" encoding="UTF-8"?> <RESPONSE> <MULTIPLE> <SINGLE> <KEY name="id"> <VALUE>5</VALUE> </KEY> <KEY name="username"> <VALUE>testws8739153</VALUE> </KEY> </SINGLE> </MULTIPLE> </RESPONSE> |
JSON
PostData Example:
$token = 'ce4d384c0c008b69fb409258cec722ba'; $randval = mt_rand(999, 9999999); $userdata[] = array( 'username' => 'testws' . $randval, 'firstname' => 'testws', 'lastname' => $randval, 'password' => 'Testws.' . $randval, 'email' => 'testws+' . $randval . '@example.com', 'city' => 'Vancouver', 'country' => 'CA', 'idnumber' => $randval );
$postdata = array( 'wstoken' => $token, 'wsfunction' => 'core_user_create_users', 'moodlewsrestformat'=>'json', 'users' => $userdata ); |
Response Example:
[ { "id": 5, "username": " testws8739153" } ] |
1.2 Users: core_user_get_users_by_field
Retrieve users information for a specified unique field.
Request
HTTP request
POST http://localhost/moodle/webservice/rest/server.php |
||
Property name | Value | Description |
Required properties | ||
wstoken | string | Valid Moodle token |
wsfunction | core_user_get_users_by_field | Function name |
Optional properties | ||
moodlewsrestformat | json | parameter to allow JSON output |
Parameters
Property name | Value | Description |
Required properties | ||
field | string | the search field can be 'id' or 'idnumber' or 'username' or 'email' |
values[0] | String, int | Value for search field |
Response
XML
PostData Example:
$token = 'ce4d384c0c008b69fb409258cec722ba';
$postdata = array( 'wstoken' => $token, 'wsfunction' => 'core_user_create_users', 'field' => 'id', 'values[0]'=> '5',
); |
Response Example:
<?xml version="1.0" encoding="UTF-8"?> <RESPONSE> <MULTIPLE> <SINGLE> <KEYname="id"> <VALUE>5</VALUE> </KEY> <KEYname="username"> <VALUE>testws8739153</VALUE> </KEY> <KEYname="firstname"> <VALUE>testws</VALUE> </KEY> <KEYname="lastname"> <VALUE>8739153</VALUE> </KEY> <KEYname="fullname"> <VALUE>testws 8739153</VALUE> </KEY> <KEYname="email"> <VALUE>testws+8739153@example.com</VALUE> </KEY> <KEYname="address"> <VALUEnull="null"/> </KEY> <KEYname="phone1"> <VALUEnull="null"/> </KEY> <KEYname="phone2"> <VALUEnull="null"/> </KEY> <KEYname="icq"> <VALUEnull="null"/> </KEY> <KEYname="skype"> <VALUEnull="null"/> </KEY> <KEYname="yahoo"> <VALUEnull="null"/> </KEY> <KEYname="aim"> <VALUEnull="null"/> </KEY> <KEYname="msn"> <VALUEnull="null"/> </KEY> <KEYname="department"> <VALUE/> </KEY> <KEYname="institution"> <VALUEnull="null"/> </KEY> <KEYname="idnumber"> <VALUE>8739153</VALUE> </KEY> |
<KEYname="interests"> <VALUEnull="null"/> </KEY> <KEYname="firstaccess"> <VALUE>0</VALUE> </KEY> <KEYname="lastaccess"> <VALUE>0</VALUE> </KEY> <KEYname="auth"> <VALUEnull="null"/> </KEY> <KEYname="confirmed"> <VALUEnull="null"/> </KEY> <KEYname="lang"> <VALUEnull="null"/> </KEY> <KEYname="theme"> <VALUEnull="null"/> </KEY> <KEYname="timezone"> <VALUEnull="null"/> </KEY> <KEYname="mailformat"> <VALUEnull="null"/> </KEY> <KEYname="description"> <VALUEnull="null"/> </KEY> <KEYname="descriptionformat"> <VALUEnull="null"/> </KEY> <KEYname="city"> <VALUE>Vancouver</VALUE> </KEY> <KEYname="url"> <VALUEnull="null"/> </KEY> <KEYname="country"> <VALUE>CA</VALUE> </KEY> <KEYname="profileimageurlsmall"> <VALUE> http://localhost/moodle/pluginfile.php/88/user/icon/f2</VALUE> </KEY> <KEYname="profileimageurl"> <VALUE> http://localhost/moodle/pluginfile.php/88/user/icon/f1</VALUE> </KEY> <KEYname="customfields"> <MULTIPLE/> </KEY> <KEYname="preferences"> <MULTIPLE/> </KEY> </SINGLE> </MULTIPLE> </RESPONSE> |
JSON
PostData Example:
$token = 'ce4d384c0c008b69fb409258cec722ba'; 'wstoken' => $token, 'wsfunction' => 'core_user_create_users', 'moodlewsrestformat'=>'json', 'field' => 'id', 'values[0]'=> '5',
); |
Response Example:
[ |
1.3 Users: core_user_update_users
Update a user's information. Use fields similar to to the create user web service.
Request
HTTP request
POST http://localhost/moodle/webservice/rest/server.php |
||
Property name | Value | Description |
Required properties | ||
wstoken | string | Valid Moodle token |
wsfunction | core_user_update_users | Function name |
Optional properties | ||
moodlewsrestformat | json | parameter to allow JSON output |
Parameters
Property name | Value | Description |
Required properties | ||
users[0][id] | int | ID of the user |
users[0][username] | string | Username policy is defined in Moodle security config |
users[0][password] | string | Plain text password consisting of any characters |
users[0][firstname] | string | The first name(s) of the user |
users[0][lastname] | string | The family name of the user |
users[0][email] | string | A valid and unique email address |
Optional properties | ||
users[0][auth] | string | Default to "manual" Auth plugins include manual, ldap, imap, etc |
users[0][idnumber] | string | Default to "" An arbitrary ID code number perhaps from the institution |
users[0][lang] | string | Default to "en". Language code such as "en", must exist on server |
users[0][theme] | string | Theme name such as "standard", must exist on server |
users[0][timezone] | string | Timezone code such as Australia/Perth, or 99 for default |
users[0][mailformat] | int | Mail format code is 0 for plain text, 1 for HTML etc |
users[0][description] | string | User profile description, no HTML |
users[0][city] | string | Home city of the user |
users[0][country] | string | Home country code of the user, such as AU or CZ |
users[0][firstnamephonetic] | string | The first name(s) phonetically of the user |
users[0][lastnamephonetic] | string | The family name phonetically of the user |
users[0][middlename] | string | The middle name of the user |
users[0][alternatename] | string | The alternate name of the user |
Response
XML
PostData Example:
$token = 'ce4d384c0c008b69fb409258cec722ba'; 'id' => 5, 'city' => mt_rand(0, 1000) ); $postdata = array( 'wstoken' => $token, 'wsfunction' => 'core_user_update_users', 'users' => $userdata ); |
Response Example:
<?xml version="1.0" encoding="UTF-8" ?> <RESPONSE> </RESPONSE> |
JSON
PostData Example:
$token = 'ce4d384c0c008b69fb409258cec722ba'; 'id' => 5, 'city' => mt_rand(0, 1000) ); $postdata = array( 'wstoken' => $token, 'wsfunction' => 'core_user_update_users', 'moodlewsrestformat'=>'json', 'users' => $userdata ); |
Response Example:
null |
2.1 Enrolments: enrol_manual_enrol_users
Manual enrol users. The Role ID is the numeric value representing the role. By default student role has the ID 5.
Request
HTTP request
POST http://localhost/moodle/webservice/rest/server.php |
||
Property name | Value | Description |
Required properties | ||
wstoken | string | Valid Moodle token |
wsfunction | enrol_manual_enrol_users | Function name |
Optional properties | ||
moodlewsrestformat | json | Parameter to allow JSON output |
Parameters
Property name | Value | Description | |
Required properties | |||
enrolments [0][ roleid] | int | Role to assign to the user | |
enrolments [0][ userid] | int | The user that is going to be enrolled | |
enrolments [0][ courseid] | int | The course to enrol the user role in | |
Optional properties | |||
enrolments [0][ timestart] | int | Timestamp when the enrolment start | |
enrolments [0][ timeend] | int | Timestamp when the enrolment end | |
enrolments [0][ suspend] | int | set to 1 to suspend the enrolment |
Response
XML
PostData Example:
'roleid' => 5, 'userid' => 2, 'courseid' => 1 ); $postdata = array( 'wstoken' => $token, 'wsfunction' => 'enrol_manual_enrol_users', 'enrolments' => $enrolments ); |
Response Example:
<?xml version="1.0" encoding="UTF-8" ?> <RESPONSE> </RESPONSE> |
JSON
PostData Example:
$token = 'ce4d384c0c008b69fb409258cec722ba'; 'roleid' => 5, 'userid' => 5, 'courseid' => 1 ); $postdata = array( 'wstoken' => $token, 'wsfunction' => 'enrol_manual_enrol_users', 'moodlewsrestformat'=>'json', 'enrolments' => $enrolments ); |
Response Example:
null |
Errors:
Error Message Structure
REST
<?xml version="1.0" encoding="UTF-8"?> <EXCEPTION class ="invalid_parameter_exception"> <MESSAGE>Invalid parameter value detected </MESSAGE> <DEBUGINFO></DEBUGINFO> </EXCEPTION> |
<Common Causes of Errors:
The most common reasons why webservice error occurs are the following:
- Invalid parameter: The values that you are passing doesn't meet the web service function parameter type standard. Pease make sure you are passing the right values by going through this document meticulously.
Example:
- If you pass a space in username, the webservice will result in error.
- When you need to pass a country code for using core_user_create_user(), be sure the country code is 2-letter standard code
- Token error: Please check if you're using the right token created for the web service you intend to use.
- Invalid Access: Be sure you have the access to run the webservice (if the webservice is created for authorized users).
- Not Passing all mandatory fields: You can ignore the optional parameters to be passed. But the mandatory fields must be passed
- Web service disabled: Ensure necessary web services are enabled (Plugins > Webservices > External
Services > Edit)
- Protocol Disabled: Ensure REST and XML-RPC protocol are enabled (Plugins > Webservices > Manage protocols).
Comments
0 comments
Please sign in to leave a comment.