Web Services:OK Tech Web Services
Note: You are currently viewing documentation for Moodle 1.9. Up-to-date documentation for the latest stable version is available here: Web Services:OK Tech Web Services.
- 1 Purpose
- 2 History
- 3 Others Forks
- 4 Installation
- 5 List of exchanged data types
- 6 List of supported operations
- 7 Authentication
- 8 Testing the Web Service with SoapUI
- 9 Testing the Web Service with a browser
- 10 Writing a client in PHP
- 11 Writing a client in Java
- 12 Writing a client in Python
- 13 Writing a client in C, C++, Objective-C
- 14 Writing clients of smartphones/tablets
- 15 Extending the OK Tech Web Service
- 16 The future
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.
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".
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).
- Lightwork Web Services use a lighter version for its specific processing of grades and assignments.
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 .
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.
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.
- first login : http://yourmoodle/wspp/service_pp2.php?username=alogin&password=apassword&wsfunction=login&wsformatout=dump
- take note of the returned client and session key values to be send in all subsequent operations
loginReturn Object ( [client] => 40867 [sessionkey] => ad497b0f303506ea3c6ef1742dc414e6 )
- call the target operation : http://yourmoodle/wspp/service_pp2.php?client=40867&sesskey=ad497b0f303506ea3c6ef1742dc414e6&wsfunction=get_my_courses&wsformatout=dump
- don't forget to logout : http://yourmoodle/moodle.195/wspp/service_pp2.php?client=40867&sesskey=ad497b0f303506ea3c6ef1742dc414e6&wsfunction=logout&wsformatout=xml
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.
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
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
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/
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 ;-)
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.
- There is also a project http://code.google.com/p/wsdl2objc/ to convert the WSDL emitted by OK Tech to stub classes in Objective C ; thus you should be able to also use the SOAP protocol on iOS devices. Seer this discussion http://moodle.org/mod/forum/discuss.php?d=175617
Extending the OK Tech Web Service
See this page on the git repository of the projet
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 ) 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 ;-)