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

Using web services: Difference between revisions

From MoodleDocs
m (rewording)
m (rewording)
Line 17: Line 17:


== Enabling web service function documentation ==
== Enabling web service function documentation ==
[[Image:Web services documentation.jpg|thumb|Enabling web service function documentation]]
[[Image:Security keys and documentation.jpg|thumb|Security keys page with documentation link]]
 
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 [[How_to_get_a_security_key|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.
Enabling web service function documentation (also on the Manage protocols page) results in user-specific web service descriptions being available for each user on their [[How_to_get_a_security_key|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 ==
== Creating a service ==
[[Image:Add external service.jpg|thumb|left|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.
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.
You can enable only the specific functions that you need to expose, so not compromising on security.
 
[[Image:Create a service.jpg|thumb|Creating a service|left]]
# Access ''Settings > Site administration > Plugins > Web services > External services''
# Access ''Settings > Site administration > Plugins > Web services > External services''
# Click Add new custom service
# 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'


[[Image:Create a service.jpg|thumb]]The ''Add a service'' page should be displayed.
==Adding functions to the service==
 
[[Image:Select a web service function.jpg|thumb|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 [[Development:Creating_a_web_service_client|Creating a web service client]].
*  "''Authorised users only''": if enabled, you will need to select the authorised users manually. Otherwise all Moodle users are allowed, at the condition they have the [https://docs.moodle.org/en/How_to_enable_web_services_for_ordinary_users#Enable_capabilities_to_users 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 only'' and ''required capability''
  Click on '''Add service'''
 
= Add functions to the service =
[[Image:Add functions to the service.jpg|thumb]][[Image:Select a web service function.jpg|thumb]]At this moment your service is empty and doesn't do much. You want to add some web service function to it. Your choice will be dictated by what you allow the external application to do. For now you are going to select 'Create group' function for the only reason that it is the function used as example to [https://docs.moodle.org/en/Development:Creating_a_web_service_client create a web service client].
 
  Click '''Add functions''' link,
  Select 'create group' function and click '''Add functions''' button
 
[[Image:Function added-1.jpg|thumb]]You should be back to the service function list. Next to each function you can see a 'Required capabilies' field. Users need these capabilities to run each function. However there is some exception. Sometimes a function use case could not require the entire capability list. The only way to be 100% sure is to read the web service function documentation (even though they are currently not indicated see MDL-XXX). Core developers try to keep capability names clear enough that it should straight forward for administrator to guess it right.
 
 
 
 
 
 
 
 
 
 
 


# 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==


= Enable capabilities to users=
The final step is to grant appropriate permissions. The following capabilities should be allowed:
The last step, and the trickiest, is to grant the right permission to the users. They would need the following capabilities:
* "''moodle/webservice:createtoken''" so the user can generate a security key.
* "''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 [https://docs.moodle.org/en/Manage_roles Manage roles] documentation.


* [[Capabilities/moodle/webservice:createtoken|moodle/webservice:createtoken]] - for allowing users to generate a security key
* [[Capabilities/webservice/rest:use | webservice/rest:use]], [[Capabilities/webservice/soap:use | webservice/soap:use]], [[Capabilities/webservice/xmlrpc:use | webservice/xmlrpc:use]], [[Capabilities/webservice/amf: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.


[[Image:Security keys and documentation.jpg|thumb]]Once done, the web service should be set up. The user can [https://docs.moodle.org/en/How_to_get_a_security_key retrieve his/her personal security key] and copy it in an external application.
Once done, the web service should be set up. Users can [[How_to_get_a_security_key|obtain a personal security key]] and copy it in an external application.


= See also=
= See also=
* [https://docs.moodle.org/en/Web_Services Web services]
* [[Web Services]]
* [[How to enable web services for an external system]]
* [[How to enable web services for an external system]]


[[Category:Web Services]]
[[Category:Web Services]]

Revision as of 13:44, 27 January 2011

Template:Moodle 2.0This 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

Enabling web services
  1. Access Settings > Site administration > Advanced features
  2. 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

Enabling protocols

Usually external applications that users wish to use dictate which protocols should be enabled.

  1. Access Settings > Site administration > Plugins > Web services > Manage protocols
  2. Enable the protocols (SOAP, REST, XMLRPC, AMF, ...) as required

Enabling web service function documentation

Security keys page with documentation link

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.

Creating a service
  1. Access Settings > Site administration > Plugins > Web services > External services
  2. 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.)
  3. Enter a name and check Enabled
  4. Click the button 'Add service'

Adding functions to the 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.

  1. Click 'Add functions' link
  2. 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:

Once done, the web service should be set up. Users can obtain a personal security key and copy it in an external application.

See also

Retrieved from "https://docs.moodle.org/33/en/index.php?title=Using_web_services&oldid=80874"
Powered by MediaWiki