Creating a web service client
To see the API Documentation, connect as Admin and go to Administration > Plugins > Web services > API Documentation
Simple REST request example
To quickly test the web service works you can visit the end point from the browser or via curl. For example to call a function via REST protocol:
$ curl "https://your.site.com/moodle/webservice/rest/server.php?wstoken=...&wsfunction=...&moodlewsrestformat=json"
Customise the parameters wstoken and wsfunction to match the server side setup. Append additional parameters for the function call as needed. The moodlewsrestformat parameter affects the response format and can be either xml (default) or json.
Officially supported protocols
- The Moodle REST server accepts GET/POST parameters and return XML/JSON values. This server is not RESTfull.
- The Moodle SOAP server is based on the Zend SOAP server (itself based on the PHP SOAP server). Zend publishes a Zend SOAP client. The current server implementation doesn't fully work with Java/.Net because we didn't generated a fully describe WSDL yet. If you are working on a Java/.Net client, follow or participate to the tracker issues MDL-28988 / MDL-28989
- The Moodle XML-RPC server is based on Zend XML-RPC server. Zend also publishes a Zend XML-RPC client.
- the Moodle AMF server is based on the Zend AMF server. The test client can be found in Settings blocks > Site Administration > Development > Web service test client > AMF Test client.
Demo client examples
Demo client sample codes can be downloaded on Github.
For HTML5 app creators, you can also find:
- a nice phonegap / Jquery mobile template
Node.js apps can use the moodle-client module.
How to get a user token
Your client can call the script located in /login/token.php with a simple HTTP request. We highly recommend to do it securely with HTTPS. The required parameters are:
- service shortname - The service shortname is usually hardcoded in the pre-build service (db/service.php files). Moodle administrator will be able to edit shortnames for service created on the fly: MDL-29807. If you want to use the Mobile service, its shortname is moodle_mobile_app. Also useful to know, the database shortname field can be found in the table named external_services.
Difference between Moodle versions
- Moodle 2.2 and later: the script can generate user tokens for any service shortname (of course users must be allowed on the service, see How to create and enable a web service).
- Moodle 2.1: the script can only generate tokens for the official built-in mobile service. However the script can returns tokens for other services, they just need to have been previously generated.
About service shortname
At the moment a service can have a shortname if you:
- create the service as a built-in service (in db/services.php files)
- add the shortname manually in the DB. Note: we'll add the admin UI for shortname later (MDL-30229)
Moodle 2.0 to 2.2
HTML is the format sent/received by web service functions. All returned file urls are converted to 'http://xxxx/webservice/pluginfile.php/yyyyyyyy'
Moodle 2.3 and later
Since Moodle 2.3 you can add few GET/POST parameters to your request (for devs who have a good knowledge of File API and format_text()):
- moodlewssettingraw => false by default. If true, the function will not apply format_text() to description/summary/textarea. The function will return the raw content from the DB.
- moodlewssettingfileurl => true by default, returned file urls are converted to 'http://xxxx/webservice/pluginfile.php/yyyyyyyy'. If false the raw file url content from the DB is returned (e.g. @@PLUGINFILE@@)
- moodlewssettingfilter => false by default. If true, the function will filter during format_text()