Moodle Web Services API - Interfaces
Moodle Web Services API - Interfaces
Moodle Web Services API - Interfaces
1. Introduction
The Moodle web services API is made up of an object-oriented core with a central server class
containing the main logic for the functions available via the web services (WS) interface. This class is
meant to be extended to allow for many transport methods to use the same core functionality. The
example transport interface supplied with this package is a SOAP transport layer.
The general idea behind the WS interface is that a client will start a session with the server and
can send commands to the server when that session is active. The session is initiated by sending login
information to the Moodle WS and receiving a session ID and key which are required for all WS
commands to execute successfully.
2. Usage
There is a very thin layer above the server and transport implementations and that is a small
PHP script called /ws/service.php. This script is the endpoint for WS communications on the
server side and takes a single paramter, type, which will specify a specific transport protocol and
attempt to start a server sub-class based on that protocol. In the supplied example it the endpoint is
/ws/service.php?type=soap.
When using the WSDL interface the supplied /ws/wsdl.php script will return a WSDL file,
moodlews.wsdl, that will be appropriate for the server that particular Moodle installation is running
on. Because the Moodle uses the NuSOAP library you can have NuSOAP dynamically generate a
WSDL file for you. This is done by pointing your WSDL URL at
/ws/service.php?type=soap&wsdl. This will generate a WSDL file for you on-the-fly but is
much slower than calling /ws/wsdl.php itself. However allowing NuSOAP to dynamically generate
this file for you can help out a lot with debugging or adding new service methods.
3. API
Each method will have the following information: title, description, table of input parameters
(complete with type) and an explanation of the return value.
2.1 login
Initiates a WS session for a given Moodle user. All future commands send in will have
restrictions checked against this Moodle user's system permissions.
Input parameters:
username String The Moodle username to login with.
password String The Moodle password to login with.
1 / 16
J. Filip Moodle Web Services Interfaces
Return:
An object containing two elements:
– client an Integer WS client session record ID.
– sessionkey a String WS client session key.
2.2 logout
Closes a given WS session thus invalidating the client ID and session key for any future WS
commands.
Input parameters:
client Integer A WS client session record ID.
sesskey String A WS client session key.
Return:
A boolean value with True indicating a successful logout and False indicating the logout failed.
2.3 edit_user
Takes a group of user records and performs the specified editing operations on them (specified
per-record). Each object in the input array must have an 'action' element with one of three possible
values specified:
– Add
– Update
– Delete
If performing an Add you want to specify as many fields as possible with the minimum being:
– idnumber
– firstname
– lastname
– username
– password
– email
If performing an Update you only need supply the idnumber field and any other attributes you wish to
modify for the given user. With a delete operation the only attribute required is the idnumber field of
the record to be deleted.
Input parameters:
client Integer A WS client session record ID.
sesskey String A WS client session key.
users Array An array of user objects.
Return:
An array of user objects representing each edited user record. If any error occurred during
2 / 16
J. Filip Moodle Web Services Interfaces
processing of any user object, the corresponding return object for that record will have an error
attribute set with an error string indicating the failure.
2.4 get_user
Takes an array of user idnumber values to return the user records.
Input parameters:
client Integer A WS client session record ID.
sesskey String A WS client session key.
userids Array An array of user ID values.
idfield String The database field that the user ID values
correspond to (i.e. 'idfield' or 'id').
Return:
An array of user objects representing each requested user record. If any error occurred during
processing of any user record, the corresponding return object for that record will have an error
attribute set with an error string indicating the failure.
2.5 edit_course
Takes a group of course records and performs the specified editing operations on them
(specified per-record). Each object in the input array must have an 'action' element with one of three
possible values specified:
– Add
– Update
– Delete
If performing an Add you want to specify as many fields as possible with the minimum being:
– idnumber
– shortname
– longname
If performing an Update you only need supply the idnumber field and any other attributes you wish to
modify for the given course. With a delete operation the only attribute required is the idnumber field
of the record to be deleted.
Input parameters:
client Integer A WS client session record ID.
sesskey String A WS client session key.
courses Array An array of course objects.
Return:
An array of course objects representing each edited course record. If any error occurred during
processing of any user object, the corresponding return object for that record will have an error
3 / 16
J. Filip Moodle Web Services Interfaces
2.6 get_course
Takes an array of course idnumber values to return the course records.
Input parameters:
client Integer A WS client session record ID.
sesskey String A WS client session key.
users Array An array of user objects.
Return:
An array of user objects representing each requested user record. If any error occurred during
processing of any user record, the corresponding return object for that record will have an error
attribute set with an error string indicating the failure.
2.7 get_grades
Retrieves grade data for a student in one or more courses.
Input parameters:
client Integer A WS client session record ID.
sesskey String A WS client session key.
userid String A user idnumber value.
courseids Array An array of course idnumber values
Return:
An array with a single element for each course requested. Each course element contains an
object made up of four attributes:
– error
– courseid
– stats
– grades
If an error occurred or there was no grade data for the student in a given course, the error attribute
will contain the error string. The courseid element just contains the course idnumber value. The
stats attribute contains an array of the following information:
4 / 16
J. Filip Moodle Web Services Interfaces
The grades attribute will contain an array of grade values for each graded activity in the course. Each
item in that array is an array of the following format:
name String The number of graded items.
maxgrade Integer A comma-separated list of all the grade values
grade String The number of points this student currently has.
percent Float The student's overall course grade as a percentage
value.
weight Float The overall weight of the total grade data.
weighted Float The overall weighted grade value.
sortOrder Integer The sorted position of this piece of grade data.
2.8 enrol_students
Attempt to enroll users as students within a specified course.
Input parameters:
client Integer A WS client session record ID.
sesskey String A WS client session key.
courseid String A course idnumber value.
userids Array An array of user idnumber values
Return:
An array with two elements:
1. error – A string containing listing any errors that occurred trying to enroll any of the users in
the requested course.
2. students – The listing of all student database records for the request course.
5 / 16
J. Filip Moodle Web Services Interfaces
xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
xmlns="http://schemas.xmlsoap.org/wsdl/"
targetNamespace="http://localhost/moodle15/ws/wsdl">
<types>
<xsd:schema targetNamespace="http://localhost/moodle15/ws/wsdl">
<xsd:import namespace="http://schemas.xmlsoap.org/soap/encoding/" />
<xsd:import namespace="http://schemas.xmlsoap.org/wsdl/" />
<xsd:complexType name="userRecord">
<xsd:add>
<xsd:element name="error" type="xsd:string" />
<xsd:element name="id" type="xsd:integer" />
<xsd:complexType name="userRecords">
<xsd:complexContent>
<xsd:restriction base="SOAP-ENC:Array">
<xsd:attribute ref="SOAP-ENC:arrayType"
wsdl:arrayType="tns:userRecord[]" />
</xsd:restriction>
</xsd:complexContent>
</xsd:complexType>
<xsd:complexType name="userDatum">
<xsd:add>
6 / 16
J. Filip Moodle Web Services Interfaces
</xsd:complexType>
<xsd:complexType name="userData">
<xsd:complexContent>
<xsd:restriction base="SOAP-ENC:Array">
<xsd:attribute ref="SOAP-ENC:arrayType"
wsdl:arrayType="tns:userDatum[]" />
</xsd:restriction>
</xsd:complexContent>
</xsd:complexType>
<xsd:complexType name="courseRecord">
<xsd:add>
<xsd:element name="error" type="xsd:string" />
<xsd:element name="id" type="xsd:integer" />
<xsd:element name="category" type="xsd:integer" />
<xsd:element name="sortorder" type="xsd:integer" />
<xsd:element name="password" type="xsd:string" />
<xsd:element name="fullname" type="xsd:string" />
<xsd:element name="shortname" type="xsd:string" />
<xsd:element name="idnumber" type="xsd:string" />
7 / 16
J. Filip Moodle Web Services Interfaces
<xsd:complexContent>
<xsd:restriction base="SOAP-ENC:Array">
<xsd:attribute ref="SOAP-ENC:arrayType"
wsdl:arrayType="tns:courseRecord[]" />
</xsd:restriction>
</xsd:complexContent>
</xsd:complexType>
<xsd:complexType name="courseDatum">
<xsd:add>
<xsd:element name="action" type="xsd:string" />
8 / 16
J. Filip Moodle Web Services Interfaces
<xsd:attribute ref="SOAP-ENC:arrayType"
wsdl:arrayType="tns:courseDatum[]" />
</xsd:restriction>
</xsd:complexContent>
</xsd:complexType>
<xsd:complexType name="gradeRecord">
<xsd:add>
<xsd:element name="name" type="xsd:string" />
<xsd:element name="maxgrade" type="xsd:integer" />
<xsd:element name="grade" type="xsd:integer" />
<xsd:attribute ref="SOAP-ENC:arrayType"
wsdl:arrayType="tns:gradeRecord[]" />
</xsd:restriction>
</xsd:complexContent>
</xsd:complexType>
<xsd:complexType name="gradeStatsRecord">
<xsd:add>
<xsd:element name="gradeItems" type="xsd:integer" />
<xsd:element name="allgrades" type="xsd:string" />
<xsd:element name="points" type="xsd:integer" />
9 / 16
J. Filip Moodle Web Services Interfaces
<xsd:restriction base="SOAP-ENC:Array">
<xsd:attribute ref="SOAP-ENC:arrayType"
wsdl:arrayType="tns:studentGradeRecord[]" />
</xsd:restriction>
</xsd:complexContent>
</xsd:complexType>
<xsd:complexType name="studentRecord">
<xsd:add>
<xsd:element name="userid" type="xsd:integer" />
<xsd:element name="course" type="xsd:integer" />
<xsd:element name="timestart" type="xsd:integer" />
<xsd:element name="timeend" type="xsd:integer" />
</xsd:complexContent>
</xsd:complexType>
<xsd:complexType name="loginReturn">
<xsd:add>
<xsd:element name="client" type="xsd:integer" />
<xsd:element name="sessionkey" type="xsd:string" />
</xsd:add>
</xsd:complexType>
<xsd:complexType name="editUserInput">
<xsd:add>
<xsd:element name="users" type="tns:userData" />
</xsd:add>
</xsd:complexType>
<xsd:complexType name="editUserOutput">
<xsd:add>
<xsd:element name="users" type="tns:userRecords" />
</xsd:add>
</xsd:complexType>
<xsd:complexType name="getUserInput">
<xsd:complexContent>
<xsd:restriction base="SOAP-ENC:Array">
<xsd:attribute ref="SOAP-ENC:arrayType"
wsdl:arrayType="xsd:string" />
</xsd:restriction>
</xsd:complexContent>
</xsd:complexType>
<xsd:complexType name="getUserReturn">
<xsd:add>
10 / 16
J. Filip Moodle Web Services Interfaces
</xsd:complexType>
<xsd:complexType name="editCourseInput">
<xsd:add>
<xsd:element name="courses" type="tns:courseData" />
</xsd:add>
</xsd:complexType>
<xsd:complexType name="editCourseOutput">
<xsd:add>
<xsd:element name="courses" type="tns:courseRecords" />
</xsd:add>
</xsd:complexType>
<xsd:complexType name="getCourseInput">
<xsd:complexContent>
<xsd:restriction base="SOAP-ENC:Array">
<xsd:attribute ref="SOAP-ENC:arrayType"
wsdl:arrayType="xsd:string" />
</xsd:restriction>
</xsd:complexContent>
</xsd:complexType>
<xsd:complexType name="getCourseReturn">
<xsd:add>
<xsd:element name="courses" type="tns:courseRecords" />
</xsd:add>
</xsd:complexType>
<xsd:complexType name="getGradesInput">
<xsd:complexContent>
<xsd:restriction base="SOAP-ENC:Array">
<xsd:attribute ref="SOAP-ENC:arrayType"
wsdl:arrayType="xsd:string" />
</xsd:restriction>
</xsd:complexContent>
</xsd:complexType>
<xsd:complexType name="getGradesReturn">
<xsd:add>
<xsd:element name="grades" type="tns:studentGradeRecords" />
</xsd:add>
</xsd:complexType>
<xsd:complexType name="enrolStudentsInput">
<xsd:complexContent>
<xsd:restriction base="SOAP-ENC:Array">
<xsd:attribute ref="SOAP-ENC:arrayType"
wsdl:arrayType="xsd:string" />
</xsd:restriction>
</xsd:complexContent>
</xsd:complexType>
<xsd:complexType name="enrolStudentsReturn">
<xsd:add>
<xsd:element name="error" type="xsd:string" />
<xsd:element name="students" type="tns:studentRecords" />
</xsd:add>
</xsd:complexType>
</xsd:schema>
</types>
<message name="mdl_soapserver.loginRequest">
11 / 16
J. Filip Moodle Web Services Interfaces
<message name="mdl_soapserver.logoutResponse">
<part name="return" type="xsd:boolean" />
</message>
<message name="mdl_soapserver.edit_userRequest">
<part name="client" type="xsd:integer" />
<part name="sesskey" type="xsd:string" />
<part name="users" type="tns:editUserInput" />
</message>
<message name="mdl_soapserver.edit_userResponse">
</message>
<message name="mdl_soapserver.edit_courseRequest">
<part name="client" type="xsd:integer" />
<part name="sesskey" type="xsd:string" />
<part name="courses" type="tns:editCourseInput" />
</message>
<message name="mdl_soapserver.edit_courseResponse">
<part name="return" type="tns:editCourseOutput" />
</message>
<message name="mdl_soapserver.get_courseRequest">
<part name="client" type="xsd:integer" />
<part name="sesskey" type="xsd:string" />
<part name="courseids" type="tns:getCourseInput" />
</message>
<message name="mdl_soapserver.get_courseResponse">
<part name="return" type="tns:getCourseReturn" />
</message>
<message name="mdl_soapserver.get_gradesRequest">
12 / 16
J. Filip Moodle Web Services Interfaces
<operation name="mdl_soapserver.login">
<documentation>MoodleWS Client Login</documentation>
<input message="tns:mdl_soapserver.loginRequest" />
<output message="tns:mdl_soapserver.loginResponse" />
</operation>
<operation name="mdl_soapserver.logout">
<documentation>MoodleWS: Client Logout</documentation>
<input message="tns:mdl_soapserver.logoutRequest" />
</operation>
<operation name="mdl_soapserver.get_course">
<documentation>MoodleWS: Get Course Information</documentation>
<input message="tns:mdl_soapserver.get_courseRequest" />
<output message="tns:mdl_soapserver.get_courseResponse" />
</operation>
<operation name="mdl_soapserver.get_grades">
<documentation>MoodleWS: Get User Grades</documentation>
13 / 16
J. Filip Moodle Web Services Interfaces
</operation>
</portType>
<binding name="MoodleWSBinding" type="tns:MoodleWSPortType">
<soap:binding style="rpc"
transport="http://schemas.xmlsoap.org/soap/http" />
<operation name="mdl_soapserver.login">
<soap:operation
soapAction="http://localhost/moodle15/ws/wsdl#login"
style="rpc" />
<input>
<soap:body use="encoded"
namespace="http://localhost/moodle15/ws/wsdl"
encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" />
</input>
<output>
<soap:body use="encoded"
namespace="http://localhost/moodle15/ws/wsdl"
encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" />
</output>
</operation>
<operation name="mdl_soapserver.logout">
<soap:operation
soapAction="http://localhost/moodle15/ws/wsdl#logout"
style="rpc" />
<input>
<soap:body use="encoded"
namespace="http://localhost/moodle15/ws/wsdl"
encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" />
</input>
<output>
<soap:body use="encoded"
namespace="http://localhost/moodle15/ws/wsdl"
encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" />
</output>
</operation>
<operation name="mdl_soapserver.edit_user">
<soap:operation
soapAction="http://localhost/moodle15/ws/wsdl#edit_user"
style="rpc" />
<input>
<soap:body use="encoded"
namespace="http://localhost/moodle15/ws/wsdl"
encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" />
</input>
<output>
<soap:body use="encoded"
namespace="http://localhost/moodle15/ws/wsdl"
encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" />
</output>
</operation>
<operation name="mdl_soapserver.get_user">
<soap:operation
soapAction="http://localhost/moodle15/ws/wsdl#get_user"
style="rpc" />
14 / 16
J. Filip Moodle Web Services Interfaces
<input>
<soap:body use="encoded"
namespace="http://localhost/moodle15/ws/wsdl"
encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" />
</input>
<output>
<soap:body use="encoded"
namespace="http://localhost/moodle15/ws/wsdl"
encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" />
</output>
</operation>
<operation name="mdl_soapserver.edit_course">
<soap:operation
soapAction="http://localhost/moodle15/ws/wsdl#edit_course"
style="rpc" />
<input>
<soap:body use="encoded"
namespace="http://localhost/moodle15/ws/wsdl"
encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" />
</input>
<output>
<soap:body use="encoded"
namespace="http://localhost/moodle15/ws/wsdl"
encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" />
</output>
</operation>
<operation name="mdl_soapserver.get_course">
<soap:operation
soapAction="http://localhost/moodle15/ws/wsdl#get_course"
style="rpc" />
<input>
<soap:body use="encoded"
namespace="http://localhost/moodle15/ws/wsdl"
encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" />
</input>
<output>
<soap:body use="encoded"
namespace="http://localhost/moodle15/ws/wsdl"
encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" />
</output>
</operation>
<operation name="mdl_soapserver.get_grades">
<soap:operation
soapAction="http://localhost/moodle15/ws/wsdl#get_grades"
style="rpc" />
<input>
<soap:body use="encoded"
namespace="http://localhost/moodle15/ws/wsdl"
encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" />
</input>
<output>
<soap:body use="encoded"
namespace="http://localhost/moodle15/ws/wsdl"
encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" />
</output>
15 / 16
J. Filip Moodle Web Services Interfaces
</operation>
<operation name="mdl_soapserver.enrol_students">
<soap:operation
soapAction="http://localhost/moodle15/ws/wsdl#enrol_students"
style="rpc" />
<input>
<soap:body use="encoded"
namespace="http://localhost/moodle15/ws/wsdl"
encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" />
</input>
<output>
<soap:body use="encoded"
namespace="http://localhost/moodle15/ws/wsdl"
encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" />
</output>
</operation>
</binding>
<service name="MoodleWS">
<port name="MoodleWSPort" binding="tns:MoodleWSBinding">
<soap:address
location="http://localhost/moodle15/ws/service.php?type=soap" />
</port>
</service>
</definitions>
16 / 16