Note:

If you want to create a new page for developers, you should create it on the Moodle Developer Resource site.

Creating a web service client: Difference between revisions

From MoodleDocs
m (Add an example of a REST request via curl first, then we can deal with details.)
(PHP library for REST added to the list)
Line 31: Line 31:


A [http://moodle.org/mod/forum/discuss.php?d=199453 Java Library for REST] can be found on [http://sourceforge.net/projects/moodlerestjava/ Sourceforge].
A [http://moodle.org/mod/forum/discuss.php?d=199453 Java Library for REST] can be found on [http://sourceforge.net/projects/moodlerestjava/ Sourceforge].
A [https://github.com/llagerlof/MoodleRest PHP Library for REST] can be found on GitHub.


== How to get a user token ==
== How to get a user token ==

Revision as of 13:22, 6 November 2018

Moodle 2.0


Moodle web service function documentation.jpg

You need to know how to setup a web service first.

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

REST
The Moodle REST server accepts GET/POST parameters and return XML/JSON values. This server is not RESTfull.
SOAP
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
XML-RPC
The Moodle XML-RPC server is based on Zend XML-RPC server. Zend also publishes a Zend XML-RPC client.
AMF
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:

Node.js apps can use the moodle-client module.

A Java Library for REST can be found on Sourceforge.

A PHP Library for REST can be found on GitHub.

How to get a user token

Moodle 2.2

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:

  • username
  • password
  • 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.

Request: https://www.yourmoodle.com/login/token.php?username=USERNAME&password=PASSWORD&service=SERVICESHORTNAME

Response: {token:4ed876sd87g6d8f7g89fsg6987dfh78d}

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)

Text formats

Moodle 2.0 to 2.2

Moodle 2.0


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

Moodle 2.3

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()

See also