Using web services
This document explains how an administrator can set up a web service for users to access a service. Each user will have a specific and unique security key (also known as a "token") to access the service.
- 1 Enabling web services
- 2 Enabling protocols
- 3 Enabling web service function documentation
- 4 Creating a service
- 5 Adding functions to the service
- 6 Enabling capabilities
- 7 Alternative settings
Enabling web services
Usually external applications that users wish to use dictate which protocols should be enabled.
- Access Administration > Site administration > Plugins > Web services > Manage protocols
- Enable the protocols (SOAP, REST, XMLRPC, AMF, ...) as required
Enabling web service function documentation
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
If none of the pre-build web services match your needs, we can create a custom service i.e. select which of the standard web service functions are available via that service.
We can enable only the specific functions that you need to expose, so not compromising on security.
- Click 'Add functions' link
- Select 'create group' function and click the 'Add functions' button
Note that deprecated functions can not be added to services although the ones that are already part of a service can remain there until they are removed from Moodle codebase.
You should be back to the service functions list. 'Required capabilities' are indicated for each function. Users need the required capabilities to run a function. The function descriptions in the API Documentation can also give you more information about the required capabilities (Administration > Site administration > Plugins > Web services > API Documentation).
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 service Required capability if set (Administration > Site administration > Plugins > Web services > Manage services >Edit link).
- The required capabilities for 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. Users should be able to obtain a personal security key.
Authorise only specific users
- Administration > Site Administration > Plugins > Web services > External Services
- Select Authorised users link (the service must have been set as Authorised users only in the Edit link)
- Select some users and click Add
Moodle indicates if some capabilities need to be assigned to an authorised user. Moreover if you click on the authorised user fullname, we can set up some specific options: IP restriction and Valid until.
Create a token
moodle/webservice:createtoken" to him/her. Finally, note that, as for authorised users, we can also set IP restriction and Valid until on a token.