Articles in this section

See more

Integrating Moodle Web Services and REST API

Avatar
Mariya Pak
  • Updated
Follow

­

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.

  1. 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.

 

  1. 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.

 

  1. 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.

 

  1. 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.

 

  1. 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

  1. Users

1.1.     core_user_create_users

1.2.     core_user_get_users_by_field

1.3.     core_user_update_users

  1. 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';

$postdata = array(

          'wstoken' => $token,

          'wsfunction' => 'core_user_create_users',

          'moodlewsrestformat'=>'json',

          'field' => 'id',

          'values[0]'=> '5',

 

);


Response Example:

[
  {
    "id": 5,
    "username": "testws8739153",
    "firstname": "testws",
    "lastname": "8739153",
    "fullname": "testws 8739153",
    "email": "testws+8739153@example.com",
    "department": "",
    "idnumber": "8739153",
    "firstaccess": 0,
    "lastaccess": 0,
    "city": "Vancouver",
    "country": "CA",
    "profileimageurlsmall": "http://localhost/moodle/pluginfile.php/88/user/icon/f2",
    "profileimageurl": " http://localhost/moodle/pluginfile.php/88/user/icon/f1"
  }
]

 

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';
$userdata[] = array(

          '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';
$userdata[] = array(

          '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:


$token = 'ce4d384c0c008b69fb409258cec722ba';
$enrolments[] = array(

          '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';
$enrolments[] = array(

          '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:

  1. 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

 

  1. Token error: Please check if you're using the right token created for the web service you intend to use.

 

  1. Invalid Access:  Be sure you have the access to run the webservice (if the webservice is created for authorized users).

 

  1. Not Passing all mandatory fields:  You can ignore the optional parameters to be passed. But the mandatory fields must be passed

 

  1. Web service disabled:  Ensure necessary web services are enabled (Plugins > Webservices > External

Services > Edit)

 

  1. Protocol Disabled: Ensure REST and XML-RPC protocol are enabled (Plugins > Webservices > Manage protocols).

 

Related articles

Comments

0 comments

Please sign in to leave a comment.