|
|
| (162 intermediate revisions by 14 users not shown) |
| Line 1: |
Line 1: |
| {{Moodle_2.0}} | | {{Template:Migrated|newDocId=/docs/apis/subsystems/external/description}} |
| | |
| == Purpose ==
| |
| This document explains how we describe and where we store the web service functions in Moodle 2.0.
| |
| | |
| We store function descriptions in the component/db/services.php file. Web services functions will be located in externallib.php files - this file name is not mandatory, but is strongly recommended.
| |
| | |
| Descriptions will be parsed by a service discovery function that will fill the database (extend the current discovery functionalities looking parsing the DB folders).
| |
| | |
| | |
| === Administration pages ===
| |
| Moodle administrators will be able to manage services. By default all services will be disabled.
| |
| | |
| List of administration functionalities:
| |
| * enable a service (all the functions into this service will be available)
| |
| * associate a web service user (the user has web service capability) to some services => a user can only call a service that he is associated with
| |
| * create a custom service (add and remove functions from this service)
| |
| * search easily function by component in order to create a custom service
| |
| Administrators will also be able to create a custom service, selecting any existing functions.
| |
| | |
| ===external_functions table===
| |
| List of web service functions. This table maps the web service name to the actual implementation of that function.
| |
| | |
| | |
| {| class="nicetable"
| |
| ! Field
| |
| ! Type
| |
| ! Default
| |
| ! Description
| |
| |-
| |
| | '''id'''
| |
| | int(10)
| |
| | auto-incrementing
| |
| |
| |
| |-
| |
| | '''name'''
| |
| | varchar(200)
| |
| |
| |
| | unique name of the external function used in web service protocols - a unique identifier for each function; ex.: core_get_users, mod_assignment_submit
| |
| |-
| |
| | classname
| |
| | varchar(100)
| |
| |
| |
| | name of the class that contains method implementation; ex.: core_user_external, mod_assignment_external
| |
| |-
| |
| | methodname
| |
| | varchar(100)
| |
| |
| |
| | static method; ex.: get_users, submit
| |
| |-
| |
| | classpath
| |
| | varchar(255)
| |
| | NULL
| |
| | optional path to file with class definition - recommended for core classes only, null means use component/externallib.php; this path is relative to dirroot; ex.: user/externallib.php
| |
| |-
| |
| | component
| |
| | varchar(100)
| |
| |
| |
| | Component where function defined, needed for automatic updates. Service description file is found in the db folder of this component.
| |
| |}
| |
| | |
| Detailed function description is stored as a complex PHP array in db/services.php file.
| |
| | |
| ===external_services table===
| |
| ''Service'' is defined as a group of web service functions. The main purpose of these ''services'' is to allow defining of granular access control for multiple external systems.
| |
| | |
| | |
| {| class="nicetable"
| |
| ! Field
| |
| ! Type
| |
| ! Default
| |
| ! Description
| |
| |-
| |
| | '''id'''
| |
| | int(10)
| |
| | auto-incrementing
| |
| |
| |
| |-
| |
| | '''name'''
| |
| | varchar(150)
| |
| |
| |
| | Name of service (gradeexport_xml_export, mod_chat_export) - appears on the admin page
| |
| |-
| |
| | enabled
| |
| | int(1)
| |
| | 0
| |
| | service enabled, for security reasons some services may be disabled- administrators may disable any service via the admin UI
| |
| |-
| |
| | requiredcapability
| |
| | varchar(255)
| |
| | NULL
| |
| | if capability name specified, user needs to have this permission in security context or in system context if context restriction not specified
| |
| |-
| |
| | restrictedusers
| |
| | int(1)
| |
| | 1
| |
| | 1 means on users explicitly listed in external_services_users may access this service, 0 means any user may use this service
| |
| |-
| |
| | component
| |
| | varchar(100)
| |
| | NULL
| |
| | Component where service defined - null means custom service defined in admin UI.
| |
| |}
| |
| | |
| ===external_services_functions table===
| |
| Lists all functions that are available in each service.
| |
| | |
| {| class="nicetable"
| |
| ! Field
| |
| ! Type
| |
| ! Default
| |
| ! Description
| |
| |-
| |
| | '''id'''
| |
| | int(10)
| |
| | auto-incrementing
| |
| |
| |
| |-
| |
| | '''externalserviceid'''
| |
| | int(10)
| |
| |
| |
| | foreign key, reference external_services.id
| |
| |-
| |
| | '''functionname'''
| |
| | varchar(200)
| |
| |
| |
| | name of external service, references external_functions.name; the string value here simplifies service discovery and maintenance
| |
| |}
| |
| | |
| ===external_services_users table===
| |
| Specifies services used by users.
| |
| | |
| {| class="nicetable"
| |
| ! Field
| |
| ! Type
| |
| ! Default
| |
| ! Description
| |
| |-
| |
| | '''id'''
| |
| | int(10)
| |
| | auto-incrementing
| |
| |
| |
| |-
| |
| | '''externalserviceid'''
| |
| | int(10)
| |
| |
| |
| | foreign key, reference external_services.id
| |
| |-
| |
| | '''userid'''
| |
| | int(10)
| |
| |
| |
| | foreign key, reference user.id
| |
| |}
| |
| | |
| | |
| === PHP array description ===
| |
| The description array described bellow may be stored in each component's db folder.
| |
| | |
| ====why a web service description ====
| |
| * in order to generate the WSDL for SOAP
| |
| * in order to generate documentation for protocol as REST or XMLRPC
| |
| * in order to clean the params automatically
| |
| | |
| ====code template ====
| |
| <code php>
| |
| | |
| $object = new object();
| |
| $object->property1 = PARAM_NUMBER;
| |
| $object->property2 = PARAM_ALPHA;
| |
|
| |
| $params = new object();
| |
| $params->objects = array($object);
| |
| $params->object = $object;
| |
| $params->primarytype = PARAM_ALPHANUM;
| |
|
| |
| $return = new object();
| |
| $return->values = array(PARAM_NUMBER);
| |
| $return->value = PARAM_NUMBER;
| |
| | |
| $functions = array(
| |
| | |
| 'functionname' => array(
| |
| 'classname' => 'component_classname_external',
| |
| 'methodname' => 'do_something',
| |
| 'classpath' => 'exernallibpath', //optional, used only in core
| |
| 'params' => $params,
| |
| 'optionalinformation' => 'Human readable text: "object" and "primarytype" parameters are optionals',
| |
| 'return' => $return,
| |
| ),
| |
|
| |
| 'secondfunctionname' => array(
| |
| 'classname' => 'component_classname_external',
| |
| 'methodname' => 'do_something_else',
| |
| 'classpath' => 'externallibpath', //optional, used only in core
| |
| 'params' => $params,
| |
| 'optionalinformation' => 'Human readable text: "object" and "primarytype" parameters are optionals',
| |
| 'return' => $return,
| |
| )
| |
| | |
| );
| |
| | |
| $services = array(
| |
| 'servicename' => array(
| |
| 'functions' => array ('functionname', 'secondfunctionname'),
| |
| 'requiredcapability' => 'some/capability:specified',
| |
| 'restrictedusers' = >1,
| |
| 'enabled'=>0, //used only when installing the services
| |
| )
| |
| );
| |
| </code>
| |
| | |
| The function name is arbitrary, but it must be globally unique. It is recommended to use component as a prefix.
| |
| | |
| === Function implementation ===
| |
| The function are store into servicelib.php classes. These classes can be found anywhere and are referenced by the servicelibpath into the function description. However it would be a common practice to place them in obvious places like a plugin lib folder.
| |
| | |
| <code php>
| |
| final class componentname_external {
| |
| static public function methodname ($params) {
| |
| clean_function_params('functioname', $params);
| |
|
| |
| /// specific function code
| |
| /// ...
| |
| }
| |
| } | |
| </code>
| |
| | |
| === Way to fill the database tables ===
| |
| The Moodle upgrade will take care of the updates. We will need to add a function into lib/upgradelib.php/upgrade_plugins() that will check all web service description.
| |
| | |
| === Return values are filtered by the servers ===
| |
| Web service function should be able to return whatever they want. Each server should be looking at the web services description and returns the expected values.
| |
| | |
| == Petr's Proposal ==
| |
| It can be found [https://docs.moodle.org/en/Development:Web_services_security#New_database_tables here].
| |
| | |
| [[Category:Web Services]]
| |
