Using web services: Difference between revisions
m (delete moodle 2 template) |
Helen Foster (talk | contribs) m (moved How to enable web services for ordinary users to Web services for ordinary users: shorter title) |
(No difference)
| |
Revision as of 17:51, 31 October 2011
This document explains how an administrator can set up a web service for users to access a service. All users will have a specific and unique security key (also known as a "token") to access the service. Each user will normally enter their own security key into an external application.
Enabling web services
- Access Settings > Site administration > Advanced features
- Check 'Enable web services' then click 'Save Changes'
Note: For security reasons, web services should only be enabled if you intend to make use of it.
Enabling protocols
Usually external applications that users wish to use dictate which protocols should be enabled.
- Access Settings > Site administration > Plugins > Web services > Manage protocols
- Enable the protocols (SOAP, REST, XMLRPC, AMF, ...) as required
Enabling web service function documentation
Enabling web service function documentation (also on the Manage protocols page) results in user-specific web service documentation being available for each user on their security keys page. This option is mainly useful to web service client developers. If nobody is creating a web service client, there is no need to enable this feature.
Creating a service
There are no default web services in Moodle so it is necessary to create a custom service i.e. select which of the standard web service functions are available via that service.
You can enable only the specific functions that you need to expose, so not compromising on security.
- Access Settings > Site administration > Plugins > Web services > External services
- Click Add new custom service
- 'Authorised users only' - If enabled, you will need to select the authorised users manually. Otherwise all users with appropriate permissions are allowed
- 'Required capability' - If enabled, any user accessing the web service will be checked against this selected capability. (This is just an additional optional security layer.)
- Enter a name and check Enabled
- Click the button 'Add service'
Adding functions to the service
Your service is currently empty and doesn't do anything. Web service functions need to be added. Your choice will be dictated by what you allow the external application to do. For now, select 'Create group' as it is the function used as an example in Creating a web service client.
- Click 'Add functions' link
- Select 'create group' function and click the 'Add functions' button
You will then be returned to the service functions list. Opposite each function is a 'Required capabilities' field. Users need these capabilities to run each function. However there are exceptions - see the web service function documentation for details.
Enabling capabilities
The final step is to grant appropriate permissions. The following capabilities should be allowed:
- moodle/webservice:createtoken - for allowing users to generate a security key
- webservice/rest:use, webservice/soap:use, webservice/xmlrpc:use, webservice/amf:use which match the enabled protocols.
- The required capabilities for the web service functions. These required capabilities are listed when you add a function to the service.
Once done, the web service should be set up. Users can obtain a personal security key and copy it in an external application.
