|
|
| (78 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 functions that can be called via web services must be declared in an external.php file somewhere. The description of the functions that can be called, and what parameters they require, is defined in their phpDoc comments.
| |
| | |
| To simulate named parameters in the PHP call, each web service function just takes a single argument $params in PHP that is an associative array. This means that the standard <tt>@param array|struct $params</tt> declaration does not provide very much information, so we have created an extended phpDoc syntax to describe what the function is expecting to find within the array. Here is a simple example:
| |
| | |
| <code php>
| |
| /**
| |
| * @param array|struct $params <-- this is standard phpDoc, but does not say much.
| |
| * @subparam string $params->username - the username
| |
| * @subparam integer $params->age optional - the user age
| |
| * @return boolean Whether a matching user exists in the Moodle database.
| |
| */
| |
| static function user_exists($params) {
| |
| // ...
| |
| } | |
| </code>
| |
| | |
| This says that the $params array must contain an entry name 'username', and can optionally contain one called 'age'. So if you wanted to call this function from PHP you could do it uses
| |
| <code php>
| |
| $params = array(
| |
| 'username' => 'fred'
| |
| );
| |
| </code>
| |
| or
| |
| <code php>
| |
| $params = array(
| |
| 'username' => 'fred',
| |
| 'age' => 13
| |
| );
| |
| </code>
| |
| | |
| Of course, normally you will not call this function from PHP, but via a web service. The $params will have to come from the SOAP or REST (or other) request. It is the job of the SOAP/REST/... server layer to translate from SOAP/REST/... format to the internal format according to some rules.
| |
| | |
| Here is a slightly more complex example:
| |
| <code php>
| |
| /**
| |
| * @param array|struct $params
| |
| * @subparam integer $params:id - a list of user ids.
| |
| * @return array $return
| |
| * @subreturn integer $return:user->id
| |
| * @subreturn string $return:user->username
| |
| * @subreturn string $return:user->lastname
| |
| */
| |
| static function get_users_by_id($params) {
| |
| // ...
| |
| } | |
| </code>
| |
| | |
| Look first at the @param part. The ':' says that the function wants an array of user ids. For example
| |
| <code php>
| |
| $params = array(
| |
| 'id' => array(13, 42, 123)
| |
| );
| |
| </code>
| |
| In more complex cases, for example the return value in the preceding example, ':' and '->' can be used in combination. That is, the get_users_by_id example might return:
| |
| <code php>
| |
| $return = array(
| |
| 0 => array(
| |
| 'id' => 13,
| |
| 'username' => 'fred.bloggs',
| |
| 'lastname' => 'Bloggs'
| |
| ),
| |
| 1 => array(
| |
| 'id' => 42,
| |
| 'username' => 'martin.dougiamas',
| |
| 'lastname' => 'Dougiamas'
| |
| ),
| |
| 2 => array(
| |
| 'id' => 123,
| |
| 'username' => 'jerome.mouneyrac',
| |
| 'lastname' => 'Mouneyrac'
| |
| )
| |
| );
| |
| </code>
| |
| | |
| Note that, in the simple case where the return type is just a primary type, like boolean for user_exists example above, there is no need to bother with @subreturn.
| |
| | |
| ==web services technical documentation==
| |
| In order to facilitate a Moodle web service client implementation, every Moodle sites will provide a page listing all function descriptions. This page also gives some useful advice for any supported protocol. To call this page: ''your_moodle/webservice/documentation.php?protocol=soap
| |
| ''
| |
| | |
| ==API - Function list==
| |
| The web service functions are [[Web_services_API_-_Function_List|listed here]].
| |
| | |
| =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]]
| |
| | |
| | |
| [[Category:Web Services]]
| |
