Note:

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

Web Services:OK Tech Web Services

From MoodleDocs
The printable version is no longer supported and may have rendering errors. Please update your browser bookmarks and please use the default browser print function instead.


Warning: This page is no longer in use. The information contained on the page should NOT be seen as relevant or reliable.


Warning: This page is no longer in use. The information contained on the page should NOT be seen as relevant or reliable.

Purpose

A major announcement of Moodle 2.0 is the Web Service Support allowing the admin to expose particular functions of Moodle for use by Administrative Systems such as HR or SIS applications or Mobile clients. All defined functions are automatically available via :

   * XML-RPC
   * AMF (Flash)
   * REST (any language)
   * SOAP (PHP only) 

This extremely elegant and promising solution will definitively make obsolete previous attempts such as the SOAP based Open Knowledge Technologies Web Services described here. However current [Moodle 2.0 implementation] suffers of two limitations :

  • The current server implementation doesn't work with Java/.Net because we didn't generated a fully describe WSDL yet.
  • The list of supported operations is still limited

This page was started in November 2010 to try to summarize the huge amount of information in this OK Tech Web Services forum and help developers still needing a Soap approach to continue to use this solution and eventually port their existing clients on a Moodle 2.0 server. Contributors are welcome to update this page, and especially help to document all parameters required and returned by operations.

It is obvious that new Web Service based developments should use the official Moodle 2.0 approach, thus helping the community to extend it.

History

The original Soap based Web Service for Moodle 1.7, was announced by Open Knowledge Technologies in March 2007 at the beginning of this discussion. My 'fork' was announced in May 2007. As you can see in the discussion above I took over the answers to most questions since mid 2007.

I kept the name OK Tech WS and to avoid confusion I added some 'pp' (my initials) ; thus I renamed the directory wspp instead of ws and the main entry point became http://yourmoodle/wspp/wsdl_pp.php

In the meantime Open Knowledge Technologies, now named Remote Learner improved internally its version, by merging some of my code, and recently documented it in chapter 14 of the PACKT book "Moodle 1.9 extension development".

In November 2010, revision 1.7 was available both at cipcnet and in Moodle CVS contrib area. On cipcnet you will find documentations and samples codes in php, Java and python.

Revision 1.7 runs best against a Moodle 1.9.x server, but can be installed on a Moodle 2.0. In that case, returned informations are 'Moodle 1.9 type' only. Moodle 2.0 specific data ( course completion, conditional activities, new File API ...) are not supported.

Starting at revision 1.8 released on github https://github.com/patrickpollet/moodlews, an alternate simplified WSDL file is now generated from the PHPDocs comments inserted in code of the mdl_baseserver.class and of the associated datatypes. This considerably simplify the extension of the Web Service and the writing of the clients.

To access this simplified new version, just change the URL of the WSDL from http://yourmoodle/wspp/wsdl_pp.php to http://yourmoodle/wspp/wsdl_pp2.php. The address of the service script will be automatically changed to wspp/service_pp2.php

Programmers should shift to the new WSDL and modify their clients code accordingly. In almost all cases that change is just removing the extra method call getXXXX() to access the returned data ; in REST mode, data are always returned in the simplified scheme.

For example, in Java the operation get_my_courses directly returns a courseRecord array so the old code below :

  CourseRecord []ret = moodle.get_my_courses(lr.getClient(),lr.getSessionkey(), me,null).getCourses();

should be changed to :

 CourseRecord[] ret = moodle.get_my_courses(lr.getClient(), lr.getSessionkey(), "" + me, null);


Revision 1.8.5 (see github) now allows access in REST mode (i.e. HTTP regular parameters in input and can return data in various formats such as json (for deserialization using standard libraries such as Google's Gson) , php (php variables are serizalized and send over to php clients for deserialization), XML (using the format currently used by Moodle 2.0 WS , thus make possible to reuse parsers developped on 2.0 clients) and dump (for debugging purpose).

Others Forks

Installation

You may get it via git at https://github.com/patrickpollet/moodlews or get the lastest archive file at http://prope.insa-lyon.fr/~ppollet/moodlews/wspp_latest.tgz

See file INSTALL.TXT in the archive.

List of exchanged data types

All exchanged data types and supported operations are published in a single WSDL file.

  • Data returned by 'get' and 'edit' operations are normally arrays of records named xxxRecord. A xxxRecord maps to a Moodle entity, such as course, user, group, cohort ... and contains the returned values. An extra filed, named 'error' is always present. This field will be empty if the operation was successful or otherwise contains a localized error message.
  • Data expected by 'edit' operations are normally arrays of records named xxxDatum. Each of these records will contain the value to add, update or delete in the corresponding Moodle entity. The required action must be set in the attribute action that can be 'add', 'update' or 'delete' ( comparison will be done in a case-insensitive way).
  • By using proxy classes generator utilities (wsdl2xxx) available in most programming languages supporting the Soap protocol, the corresponding classes will be generated ready for use.

List of supported operations

All exchanged data types and supported operations are published in a single WSDL file.

They are divided in four main groups :

  • get_XXX operations that returns an array of selected information from Moodle. All returned data are normally arrays of records described in classes named GetXXXReturn such as GetCoursesReturn, GetGradesReturn, GetUsersReturn ... These arrays are arrays of xxxRecord such as ActivityRecord, CohortRecord, GroupRecord, UserRecord ... each of these records will a have the 'error' attribute set to empty if the operation was successful or an error message otherwise.
  • edit_XXX operations that expect values to add/udpate or delete in Moodle. All data expected as input are normally arrays of records described in classes named EditXXXInput such as EditUsersInput, EditCoursesInput ... These array are arrays of xxxDatum such as CourseDatum, ForumDatum, GroupingDatum ... For each of these records, one must set an action field to 'add', 'udpate' or 'delete'. Returned data are described in classes named EditXXXOutput that are again arrays of xxxRecord ; each of these records will a have the 'error' attribute set to empty if the operation was successful or an error message otherwise.
  • convenience methods named add_xxx, delete_xxx or update_xxx that perform the same operations as their edit_xxx counterparts but expect only one input record of type xxxDatum. In these cases, is not necessary to set the 'action' field to add/update or delete. This will be done internally. Returned data is the same as the edit_xxx operations, i.e. an array containing the completed record, with the error field set or not.
  • other miscellaneous operations : login, logout, has_role_incourse ...

For a detailed list of operations and exchanged data type, see the following sections about writing clients in various languages .

Authentication

This Web Service uses only the login/password authentication method. In the first versions (less that 1.6.1) this account must be a account for which authentication could be done 'silently', that is not using an external Web Page such as CAS or Shibboleth.

Starting at revision 1.6.1, to avoid disclosing a real admin login/password to developers of other information systems you should install the new authentication plugin located in wspp/auth/webservice. Copy this folder into moodle/auth folder and go to your site administration/accounts/authentication and enable the Web Service plugin.

THIS IS NOT NEEDED WITH MOODLE 2.0 since we use the already installed webservice authentication plugin. Just make sure you enable it in Site Administration / Plugins /Authentication.

Then create a new account on your Moodle site, say wsaccess and set webservice as the authentication method. Give to this account all the required capabilities compatible with your site security and the operations you want to allow ... (for example if you do not want any add_user, add_course ..., don't give him the corresponding capabilities).

Now developers of external informations systems, connecting to Moodle via this Web Service account will not be allowed to connect the "regular way"...

Testing the Web Service with SoapUI

If you plan to use the SOAP protocol, this is definitely the easiest way to make sure that the installation of the plugin has been successful and to discover the operations and required parameters. I you can understand french a demo video is here.

You have to call the WSDL serving scripts, either http://yourmoodle/wspp/wsdl_pp.php or http://yourmoodle/wspp/wsdl_pp2.php depending if you want to use the 'old data format' or the simplified one.

Testing the Web Service with a browser

The service script (http://yourmoodle/wspp/service_pp2.php) will automatically swap from SOAP to REST if it detect two HTTP parameters (either GET or POST) named wsfunction and wsformatout. So you can easily test the WS using a regular browser.

  • take note of the returned client and session key values to be send in all subsequent operations
 loginReturn Object
 (
   [client] => 40867
   [sessionkey] => ad497b0f303506ea3c6ef1742dc414e6
 )


You may also use the 'singleshot mode' by supplying two parameters named wsusername and wspassword. In that case the service routine will automatically login the user, add to the needed client and sessionkey parameters, perform the requested target operation and do a logout.

for example : http://yourmoodle/wspp/service_pp2.php?wsusername=alogin&wspassword=apassword&wsfunction=get_roles&wsformatout=json

Writing a client in PHP

The easiest way to write clients in PHP is to use the supplied utility wsld2php.php.

On the client machine, that must have PHP 5.x and the php5 soap (and php curl if you plan to use REST) extension installed :

  • Copy the wspp/wsdl2php.php and the wspp/clients/auth.php.dist file in some directory
  • Rename the file aut.php.dist to auth.php and edit it to supply an username and a password for the user you want to use to access the Web Service. It could be an admin user or an user restricted to the 'webservice' authentication method.
  • On the command line, run :
   php ./wsdl2php.php http://yourmoodle/wspp/wsdl_pp2.php 
  • This will generate two PHP stub classes, named Mdl_soapserver.php and Mdl_restserver.php with all supported operations declared as methods, and a set of helper classes for all exchanged data types.
  • It will also create two folders named tests and testsrest with a PHP script for testing each available operation.

Documentation for operations and samples codes in PHP are available here

Writing a client in Java

Using Apache Axis 1.4 library

The javadoc of all datatypes and operations is available here (updated at every release). Supported operations are described in class MoodleWSBindingStub

A sample code using Apache axis-1.4 library can be downloaded here

And with the new WSDL (recommended) :

javadoc is here( see class Mdl_soapserverBindingStub.html for Apache Axis 1.4 client

and here the simplified version of the Java Test class

Using KSoap2 library

Efforts to provide clients using the KSoap2 library such as Android smartphones are described here

Javadoc is here for Ksoap2 based clients.

Using Google's Gson library

In REST mode, by specifying json as output format, you can use Google gson to deserialize the returned data. See this project https://github.com/patrickpollet/moodlews_gson for a generating tool of stub and helper classes.

Writing a client in Python

With soappy library see http://cipcnet.insa-lyon.fr/Members/ppollet/public/moodlews/python-notes/

With ZSI see http://cipcnet.insa-lyon.fr/Members/ppollet/public/moodlews/plone-python-notes-zsi/

Writing a client in C, C++, Objective-C

I have no experience in C, C++ or their derivatives. Nevertheless I tested the gSoap utilities wsdl2h and soap2cpp utilities against the latest wspp/wsdl_pp2.php and got 5.9Mo of quite sound C++ code !!! that looks very similar to what I am used to in Java ... I stopped here but I guess it is worth a try ?

The only drawback I see is that the service URL and the namespace are 'hardcoded' in all the generated classes and XML. I found 1035 occurences of the string 'localhost/moodle.195' in the generated code (that's the reason I dropped apache Axis for Java and swapped to KSoap2)

But that could be easily changed by using some global constants of your application, or requesting it as a new feature to gSoap author ;-)

see http://moodle.org/mod/forum/discuss.php?d=173428#p761251

Writing clients of smartphones/tablets

  • On Android based based devices, java and either the jars files provided with moodlews_ksoap2 (for SOAP protocol) or moodlews_gson (for REST protocol in input and json on output) are your best choices.
  • On iOS devices, you should turn to the REST mode ; currently you will still have to manually create the HTTP request parameters ; it you select 'wsformatout' as 'json', parsing results to Objective-C classes should be quite simple. See this discussion http://moodle.org/mod/forum/discuss.php?d=173428.

Extending the OK Tech Web Service

See this page on the git repository of the projet

The future

Efforts are in progress in two directions :

  • Making the whole of OK Tech Web Services compatible with the 'proprietary format' of Moodle 2.0 Web Service, that is automatically generate from the current WSDL the PHP classes and required methods (see [1]) in a local/oktech/externallib.php script. And this without changing the current infrastructure to keep compatibility for my existing clients/users. This has been committed as an alpha version of github starting at https://github.com/patrickpollet/moodlews/commit/d5349f2db42d570579a9ead201d0a923f04f6967
  • Parsing the Moodle 2.0 input/output format (hard coded in scripts externallib.php sprinkled all over Moodle's core code) to produce a WSDL (or one by every service configured by Moodle administrator) , thus allowing automatic generation of clients stubs and helper classes in almost any language, like OK Tech does at the moment.

This will be done at the pace of an old man, two years away from retirement and extremely busy with his two grand-children ;-)

See also