|
|
| (82 intermediate revisions by 14 users not shown) |
| Line 1: |
Line 1: |
| {{Template:Work in progress}}{{Moodle_2.0}} | | {{Template:Migrated|newDocId=/docs/apis/subsystems/external/}} |
| | |
| =Introduction= | |
| This page described the Web Services module implemented for Moodle 2.0<br>
| |
| The tracker issue is here: MDL-12886<br>
| |
| This module is been implemented by the [http://blogs.dfwikilabs.org/moodle_ws/ DFWS Team] and Moodle.
| |
| | |
| =Implementation=
| |
| Web Services module has been conceived in a purpose to be ported on different Moodle version, and also on different project. It has also for purpose to support multiple web service protocols (REST, SOAP, XML-RPC and AMF). Adding a new protocol support should be relatively easy.
| |
| | |
| == How it works ==
| |
| #The client sends a username and password to the web service protocol server script.
| |
| #The protocol server returns a session token for that user account (how this is sent depends on the protocol).
| |
| #The client calls a particular web service function (module name, function name, and function parameters), including the session token.
| |
| #The protocol server uses the token to check that the session is still active.
| |
| #The protocol server call the matching external function, located in a external.php file inside the relevant module.
| |
| #The external function checks that the current user has_capability to do this operation.
| |
| #The external function calls the matching Moodle core function (in lib.php usually).
| |
| #The core function can return a result to the external function.
| |
| #The external function will return a result to the protocol server.
| |
| #The protocol server returns the result to the client.
| |
| | |
| [[Image:Web_service_graph.jpg]]
| |
| | |
| ==phpDoc format==
| |
| All callable functions are declared into each external.php. Web service descriptions are defined into their respective phpDoc.
| |
| | |
| Every web service function is coded with one parameter only. It's an associative array $params containing all the "real" parameters.
| |
| Because a "real" parameter can be an array of (array of...) primary type, we represent an array by the character ':' or '->'. The colon character represents a non associative array/list (it can have multiple values). The arrow chatacter represents an object (associative array).
| |
| | |
| Here are few examples how to write a docblock for a web service function
| |
| | |
| All "real" parameters are primary types:
| |
| <code php>
| |
| /**
| |
| * @param array|struct $params - this line is mandatory for every web service function
| |
| * @subparam string $params->username - the username
| |
| * @subparam integer $params->age optional - the user age
| |
| * @return boolean result
| |
| */
| |
| static function find_user($params) {
| |
| } | |
| </code>
| |
| | |
| The "real" parameters is a list/array of user objects:
| |
| <code php>
| |
| /**
| |
| * @param array|struct $params
| |
| * @subparam string $params:user->username - the username
| |
| * @subparam integer $params:user->age optional - the user age
| |
| * @return array $return
| |
| * @subreturn string $return:user->username
| |
| * @subreturn integer $return:user->id
| |
| * @subreturn string $return:user->lastname
| |
| */
| |
| static function find_users($params) {
| |
| } | |
| </code>
| |
| You can also see that we describe return value the same way as we describe "real" parameters. One exception, if the return value is a primary type (as in the first example), we do not need @subparam line.
| |
| | |
| ==web services technical documentation==
| |
| In order to facilitate a Moodle web service client implementation, we provide a page listing all function descriptions. We also give some useful advice for any supported protocol.
| |
| | |
| =Authentication=
| |
| | |
| Clients needing to use a web service will need a Moodle user account with the ''''moodle/site:usewebservices'''' capability enabled. After the first login with username and password the session is retained with a token that gets passed with every web service request (until the session expires).
| |
| | |
| The Moodle administrator can control access to the site using the ''''Security -> Web services'''' page, which contains settings for:
| |
| | |
| * enabling/disabling particular protocols (SOAP, REST, AMF, XMLRPC, ...)
| |
| * configure protocol-specific settings (though we can't think of any such settings)
| |
| * configure system-wide default settings (stored in config table):
| |
| # IP whitelist
| |
| # Anything else?
| |
| * configure per-user settings (stored in user_preferences):
| |
| # IP whitelist
| |
| # Anything else?
| |
| | |
| Each protocol will call a webservice authentication function before allowing access, which will:
| |
| # Check that particular protocol is enabled for the system
| |
| # Authenticate the user using username/password and normal auth plugins (internal, LDAP etc)
| |
| # Check that the user has ''''moodle/site:usewebservices'''' at SYSTEM level.
| |
| # Check the per-user restrictions, if there are any, else check the system settings
| |
| # Create a session and return a token for the web service protocol to use.
| |
| | |
| This is probably enough (an auth/webservice is not necessary).
| |
| | |
| | |
| | |
| [[Image:Webserviceadmin.png]]
| |
