Web services

At General plugins (Local): Web service template, there's a local plugin that installs a new Web-service function. It's a very simple function that returns the message "Hello, Web". I've been trying this, and got it to work, but only after missing out one important step. So I thought it might be useful if I were to describe how I installed it: a checklist that others can follow if they have problems. The client that calls the function uses the XML-RPC protocol, but I'll also show a version that uses REST.

These are the steps I took:

• I downloaded the plugin from http://moodle.org/plugins/pluginversion.php?id=401 by clicking on the orange "Download for Moodle 2.0/Moodle 2.1/Moodle 2.2" box.

• The download arrived as a zip file. I copied it into my Moodle's local directory. Incidentally, this is /var/www/moodle/moodle/local .

• I unzipped the zip file there. This created a subdirectory named 'wstemplate' containing client, db, externallib.php, lang, README, and version.php .

• From there, I downloaded local/wstemplate/client/client.php and local/wstemplate/client/curl.php onto my PC.

• On my Moodle, I went to Site administration > Notifications. This gave me a table of three plugins, the final one of which had this row:

  Web service template   /local/wstemplate   Extension   2011101202    Moodle 2010112400   To be installed .
  

  I pressed the 'Upgrade' button below the table. This brought up a page saying

   
  local_wstemplate
  Success
  

  I pressed the 'Continue' button on it. This brought up a blank Notifications page.

• I went to Site administration > Advanced features, and checked that the "Enable web services" checkbox was ticked.

• I went to Site administration > Plugins > Web services > Manage protocols, and checked that the checkbox for XML-RPC protocol was ticked.

• I went to Site administration > Plugins > Web services > External services. This showed a table with the line

  My service   local_wstemplate   Functions   All users   Edit .
  

  So the service had evidently been installed. Clicking on "Functions" showed another table saying

  local_wstemplate_hello_world   Return Hello World FIRSTNAME. 
                                      Can change the text (Hello World) 
                                      sending a new text as parameter
  

  That concluded the installation instructions at the top of client.php .

• I went to Site administration > Plugins > Web services > Manage tokens, and clicked the "Add" link. (If you've already created any tokens, this appears below a table of them.) For the user, I selected the Web-service user that I'd created according to the instructions in Site administration > Plugins > Web services > Overview when I began experimenting with Web services last week. For the service, I selected 'My Service'.

  By the way, I'm not sure whether I needed to use my Web-services user, which I'd given special capabilities, or whether any would do. The plugin contains a source file services.php in the db subdirectory, in which there's an assignment to the $services array. (The conventions are explained at the bottom of Creating a web service and a web service function.) This sets up the service so that it is not restricted to a particular user. So I may have been able to select any user when creating my token.

• On my PC, I edited client.php to make $token the token just created. And also changed $domainname to be my Moodle's URL.

• And I ran client.php by giving the DOS command php client.php . This displayed the message "Hello, Web".

Having got that working, I modified the client so that it used the REST protocol. (That will work with the instructions above, if in the 'Manage protocols' step, you also enable REST.) This is the source code:

  echo "Demo of Web service Hello World using REST\n";
  echo "==========================================\n";

  $token = 'bb4314dsp0mdd4f986fd4fb3ac2itv59';
  $domain = 'http://moodle.ireson-paine.com';

  $welcomemsg = 'Hello, ';

  $function_name = 'local_wstemplate_hello_world';

  $params = array( 'welcomemessage' => $welcomemsg );

  $serverurl = $domain . '/webservice/rest/server.php'. '?wstoken=' . $token . '&wsfunction='.$function_name;

  require_once( './curl.php' );
  $curl = new curl;

  echo "\nAbout to call function.\n";

  $response = $curl->post( $serverurl, $params );

  echo "\nCalled function.\n";

  echo "\nResponse = $response.\n";

The coding style is slightly different than for client.php, because I use different variable names and messages. For comparison, this is client.php rewritten in the same style:

  echo "Demo of Web service Hello World using XML-RPC\n";
  echo "=============================================\n";

  $token = 'bb4314dsp0mdd4f986fd4fb3ac2itv59';
  $domain = 'http://moodle.ireson-paine.com';

  $welcomemsg = 'Hello, ';

  $function_name = 'local_wstemplate_hello_world';

  $params = array( $welcomemsg );

  $serverurl = $domain . '/webservice/xmlrpc/server.php'. '?wstoken=' . $token . '&wsfunction='.$function_name;

  require_once( './curl.php' );
  $curl = new curl;

  echo "\nAbout to call function.\n";

  $post = xmlrpc_encode_request( $function_name, $params );

  $response = xmlrpc_decode($curl->post($serverurl, $post));

  echo "\nCalled function.\n";

  echo "\nResponse = "; print_r($response); echo ".\n";

Jocelyn