|
|
| (221 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 explain how we describe and where we store the web service functions into Moodle 2.0.<br/>
| |
| We store service and function descriptions in the DB folder into a services.php file. <br/>
| |
| Web services functions will be located into servicelib.php files.<br/>
| |
| Descriptions will be parse 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.
| |
| | |
| | |
| {| class="nicetable"
| |
| ! Field
| |
| ! Type
| |
| ! Default
| |
| ! Description
| |
| |-
| |
| | '''id'''
| |
| | int(10)
| |
| | auto-incrementing
| |
| |
| |
| |-
| |
| | component
| |
| | varchar(100)
| |
| |
| |
| | Component where function defined, needed for automatic updates.
| |
| |-
| |
| | '''name'''
| |
| | varchar(150)
| |
| |
| |
| | function name: get_users, create_users,...
| |
| |-
| |
| | phpfile
| |
| | varchar(255)
| |
| |
| |
| | location where function defined - Needed for identifying
| |
| |-
| |
| | contextrestriction
| |
| | int(1)
| |
| |
| |
| | extra information - some functions may support context restrictions
| |
| |-
| |
| | requiredlogin
| |
| | int(1)
| |
| |
| |
| | extra information - some external functions may not require $USER
| |
| |-
| |
| | requiredcapabilities
| |
| | varchar(255)
| |
| |
| |
| | capability ids (separate by comma)
| |
| |}
| |
| | |
| | |
| Note about [https://docs.moodle.org/en/Development:Web_services_security#New_database_tables Petr Proposal]:<br>
| |
| * I don't think we need to insert a params description row as we have the params description into the description array.
| |
| | |
| ====New function: validate_context_restriction($currentcontext)====
| |
| | |
| Each functions that supports restrictions must:
| |
| # find out context of request from function parameters - when enrolling user to course it is a course context, when add post to chat it is chat context, etc.
| |
| # call validate_context_restriction($currentcontext) - Moodle verifies $currentcontext is equal or child of restriction context, if not exception is thrown and script terminates.
| |
| | |
| The restriction context is stored in some global variable which is initialized in lib/setup.php using data from token tables.
| |
| | |
| ===external_services table===
| |
| ''Service'' is defined as a group of web service functions.
| |
| | |
| | |
| {| 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 - The only editable field by the admin
| |
| |-
| |
| | custom
| |
| | int(1)
| |
| | 0
| |
| | Custom local service, created manually by admin or some other way (CAN BE updated automatically during the cron job => function not existing get removed). This field is useful if we want to implement an admin page where the admin selects some functions from a list of all external functions. Note: we probably need a button to desactivate all services in once.
| |
| |-
| |
| | customname
| |
| | varchar(150)
| |
| |
| |
| | As a custom service name cannot be found into lang files, we need a field for that
| |
| |}
| |
| | |
| Note about [https://docs.moodle.org/en/Development:Web_services_security#external_services Petr's Proposal]:<br>
| |
| * I removed the ''version'' row. If we want to create a special version number for a service, we could probably write it in the description array (it's not going to be changed by a Moodle administrator, it doesn't need to be saved into the database). Otherwise we could also use the moodle version to have some kind of reference about a Web Service API version.
| |
| * I removed ''requiredCapability'', it should be an array into the description (same for function capabilities)
| |
| * ''custom'' row can now be updated during Moodle upgrade.
| |
| | |
| ===external_services_functions table===
| |
| Specifies functions used by services.
| |
| | |
| {| class="nicetable"
| |
| ! Field
| |
| ! Type
| |
| ! Default
| |
| ! Description
| |
| |-
| |
| | '''id'''
| |
| | int(10)
| |
| | auto-incrementing
| |
| |
| |
| |-
| |
| | '''externalserviceid'''
| |
| | int(10)
| |
| |
| |
| | foreign key, reference external_services.id
| |
| |-
| |
| | '''externalfunctionid'''
| |
| | int(10)
| |
| |
| |
| | foreign key, reference external_functions.id
| |
| |-
| |
| | enabled
| |
| | int(1)
| |
| | 0
| |
| | function enabled, function might be disabled for security reasons - The only field editable by administrator ! This field has to be here cause a function can be enabled for the default core service but not enabled into a custom service
| |
| |}
| |
| | |
| ===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 ===
| |
| ====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 automatically the params
| |
| ====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;
| |
| | |
| $this->descriptions['function_name'] = array(
| |
| 'service' => 'service_name',
| |
| 'requiredlogin' => 0,
| |
| 'params' => $params,
| |
| 'optionalinformation' => 'Human readable text: "object" and "primarytype" parameters are optionals',
| |
| 'return' => $return );
| |
| </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]]
| |
