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.

Using web services: Difference between revisions

From MoodleDocs
No edit summary
Line 14: Line 14:


= Enable the web service function documentation =
= Enable the web service function documentation =
[[Image:Web services documentation.jpg|thumb]]
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 developer.
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 developer.


= Create a service with funtions =
= Create a service with funtions =

Revision as of 03:06, 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 the web service in Moodle

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 developer.

Create a service with funtions

A brief note about custom web services

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.

Add new custom service page

This allows you to enable only the specific functions that you need to expose, therefore increasing security. The procedure is included below.

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

externlservices settings.png

A service is a group of web service functions. You need to create first the service then add the function. When you create the service do not check "Authenticated users", we want all users (only the one with "moodle/webservice:createtoken" capability) to be able to use the web service. If you want you can select a required capability. Any user access a web service will be checked against it. It is just an additional and optional security layer for your own usage.

  Enter a name, check enable
  Click on Save changes

add webservice.png

Add a function to the service

  Settings block > Site Administration > Plugins > Web services > External Services
Click on the Functions link for the newly created service


Service functions page

  Select Add function operation, then select a function and Save changes

wsfunctionadmin.png

selectservicefunction.png

Enable capabilities to users

The last step 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.


Congratulation, the web service are set up.

User gets and use his/her security key

  1. a user goes on his/her profil block and access the security keys page. During the first access, the key is created. Note that the user can decide to regenerate a new key. He/She can also access the web service documentation if it is enabled.
  2. the user enters the key on the external application requesting a Moodle security key.