Difference between revisions of "Using web services"

Jump to: navigation, search

Note: You are currently viewing documentation for Moodle 2.2. Up-to-date documentation for the latest stable version is available here: Using web services.

(Enable capabilities to users)
(Add functions to the service)
Line 41: Line 41:
= Add functions to the service =
= Add functions to the service =
  Settings block > Site Administration > Plugins > Web services > External Services<br/>
[[Image:Add functions to the service.jpg|thumb]Add functions to the service.jpg|thumb]]At this moment your service is empty and doesn't do much. You should be on the ''Add functions to the service "My first web service"'' page.
  Click on the Functions link for the newly created service
   Select Add function operation, then select a function and Save changes
   Click '''Add functions''' link,  
  Select a function and click '''Add functions''' button
= Enable capabilities to users=
= Enable capabilities to users=

Revision as of 04:00, 18 January 2011

Template:Moodle 2.0This document explains how an administrator set up a web service for ordinary users. It is useful if you want many user to access a service. All user will have a specific and unique security key (also known as "token") to access the service.

Enable web service feature

Enable web service.jpg
For security reasons, web services should only be enabled if you intend to make use of it.
  Settings block > Site Administration > Advanced features
Check Enable web services option and Save Changes

Enable a protocol

Enable protocol.jpg

In this step you will enable some web service protocols. Usually external applications that users wish to use should dictate which protocols are enabled.

  Settings block > Site Administration > Plugins > Web services > Manage protocols
Enable the desired protocol (SOAP, REST, XMLRPC, AMF, ...)

Enable the web service function documentation

Web services documentation.jpg

On the 'Manage protocols' page you can also enable the web service function documentation. If this documentation is enabled, the user specific web service descriptions will be available to each user. This option is mainly useful to web service client developers.


Create a service

Add external service.jpg
There is no such thing as a default web service in Moodle, so anyone looking for one (or for a list of available services) may get rather confused. Instead, you must create a custom service.

Creating a custom service does not mean you are really creating an entirely new web service yourself. You don't have to program anything. Instead, a 'custom web service' just lets you select which of the standard web service functions are available via that service.

This allows you to enable only the specific functions that you need to expose, therefore increasing security.

  Settings block > Site Administration > Plugins > Web services > External Services
  Click on Add new custom service

Create a service.jpg
The Add a service page should be displayed.
  • "Authorised users": if enabled, you will need to select the authorised users manually. Otherwise all Moodle users are allowed, at the condition they have the right permissions
  • required capability: if enabled, any user accessing the web service will be checked against this selected capability. It is just an additional and optional security layer for your own usage.
  Enter a name and check enable
  Uncheck "Authorised users" and required capability
  Click on Add service

Add functions to the service

thumb]Add functions to the service.jpg
At this moment your service is empty and doesn't do much. You should be on the Add functions to the service "My first web service" page.
  Click Add functions link, 
  Select a function and click Add functions button

Enable capabilities to users

The last step, and probably the trickiest, is to grant the right permission to the users. They would need the following capabilities:

  • "moodle/webservice:createtoken" capability to the users
  • "webservice/rest:use, webservice/soap:use, webservice/xmlrpc:use, webservice/amf:use" matching the enabled protocols.
  • the required capabilities by the web service functions. These required capabilities are listed when you add a function to the service.

For more information about roles and capabilities, read the Manage roles documentation.

Once done, the web service should be set up. The user can retrieve his/her personal security key and copy it in an external application.