|
|
| (287 intermediate revisions by 14 users not shown) |
| Line 1: |
Line 1: |
| == Jerome's proposal ==
| | {{Template:Migrated|newDocId=/docs/apis/subsystems/external/description}} |
| | |
| | |
| ===external_functions===
| |
| List of external functions. Created automatically by parsing of external files.
| |
| | |
| | |
| {| 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)
| |
| |
| |
| | Name of function
| |
| |-
| |
| | enabled
| |
| | int(1)
| |
| |
| |
| | function enabled, functiosn might be disabled for security reasons
| |
| |-
| |
| | phpfile
| |
| | varchar(255)
| |
| |
| |
| | location where function defined
| |
| |-
| |
| | functionparams?
| |
| | text
| |
| | null
| |
| | ?some form of param description?
| |
| |-
| |
| | requireslogin
| |
| | int(1)
| |
| |
| |
| | extra information - some external functions may not require $USER
| |
| |-
| |
| | contextrestriction
| |
| | int(1)
| |
| |
| |
| | extra information - some functions may support context restrictions
| |
| |}
| |
| | |
| ===external_services===
| |
| ''Service'' is defined as a group of functions.
| |
| | |
| | |
| {| class="nicetable" | |
| ! Field
| |
| ! Type
| |
| ! Default
| |
| ! Description
| |
| |-
| |
| | '''id'''
| |
| | int(10)
| |
| | auto-incrementing
| |
| |
| |
| |-
| |
| | component
| |
| | varchar(100)
| |
| |
| |
| | Component where service defined, needed for automatic updates.
| |
| |-
| |
| | '''name'''
| |
| | varchar(150)
| |
| |
| |
| | Name of service (gradeexport/xml/export, mod/chat/export)
| |
| |-
| |
| | enabled
| |
| | int(1)
| |
| |
| |
| | service enabled, for security reasons some services may be disabled
| |
| |-
| |
| | version
| |
| | varchar(10)
| |
| |
| |
| | version string
| |
| |-
| |
| | requiredcapability
| |
| | varchar(150)
| |
| | null
| |
| | Required capability (tested in security context or system context if no security context specified)
| |
| |-
| |
| | custom
| |
| | int(1)
| |
| | 0
| |
| | Custom local service, created manually by admin or some other way == not parsed automatically.
| |
| |}
| |
| | |
| ===external_services_functions===
| |
| 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
| |
| |}
| |
| | |
| | |
| ==== Avalaible method for discovery ====
| |
| This paragraph exists only to define the way we'll descrive the web services. There are three possible ways to describe web services:
| |
| # a PHP array : this array will contains all params + return value. In this array we also need to make a difference between array and object. PHP Associative array has to be defined as object.<br/>
| |
| For the purpose to be compatible with many languages we should see array as list and Associative array as object. It makes me think that we should probably only deal with object, not associative array. <br/>This "array" solution has been implemented till revision 1.10 of user/external.php (CVS Head). This solution is the fastest in term of performance and should be the easier to use in order to create the servers. The way to define array/object has not been really well fixed!
| |
| # Zend reflexion + phpdoc new annotation: in this solution we use new "Moodle phpdoc annotation" in order to describe the web services. Have a look to the last revision 1.17. This solution avoid all redundancy, however it's harder to implemente, lass faster, and more difficult to maintain
| |
| # a XML file : a XML should contains all web service description. This solution is probably the more human readable (if xml is well designed).
| |
| | |
| | |
| Another point to come to, all external function should return always the same type of object (no new or missing attribut). PHP Array should be considered as list.
| |
| | |
| ===== PHP array description =====
| |
| <code php>
| |
| $this->descriptions['function_name'] = array( 'params' => array('params_name'=> PARAM_STRING),
| |
| 'optionalparams' => array( ),
| |
| 'return' => array('list:param_1' =>
| |
| array('attribut_1' => PARAM_INT,
| |
| 'attribut_2' => PARAM_STRING,
| |
| 'attribut_3' => PARAM_INT)));
| |
| </code>
| |
| | |
| Explanation:
| |
| * base is:
| |
| <code php>
| |
| $this->descriptions['function_name'] = array( 'params' => array(),
| |
| 'optionalparams' => array( ),
| |
| 'return' => array());
| |
| </code>
| |
| * when a param/return is a list so it should be called 'list:param_name'
| |
| * when a param/return is not a list so it's either a primary type (e.g. PARAM_STRING), either a object (e.g. array)
| |
| * params and optionalparams have to follow the exact order of the function
| |
| * PARAM_RAW has to be replaced by the correct type (cannot be array)
| |
| | |
| ===== Way to fill the database tables =====
| |
| Fill the ''external_functions'', ''external_services'' and ''external_services_functions'' tables from a XML file like xmldb install.
| |
