Note:

If you want to create a new page for developers, you should create it on the Moodle Developer Resource site.

External functions API: Difference between revisions

From MoodleDocs
(9 intermediate revisions by 4 users not shown)
Line 1: Line 1:
==Overview==
==Overview==
The external functions API allows you to create fully parameterised methods that can be accessed by external programs (such as [[Web services]]).
The external functions API allows you to create fully parameterised methods that can be accessed by external programs (such as [[Web services API]]).


The external functions are located in externallib.php files. Each external functions are implemented inside a class and are complemented by two description functions:
The external functions are located under every component\external\[optional\sub\] namespace (previously in externallib.php files). Each external function is implemented inside an individual class and is complemented by two description functions:
* FUNCTIONNAME_parameters() which describes the parameters of the functions
* FUNCTIONNAME_parameters() which describes the parameters of the functions
* FUNCTIONNAME_returns() which describes the return value
* FUNCTIONNAME_returns() which describes the return value
Line 8: Line 8:
The description functions uses external_description classes that have been created for this purpose.
The description functions uses external_description classes that have been created for this purpose.


== externallib.php ==
== component\external\something.php ==
* This file is located at the root of your plugin.
* This file is located under the classes/external dir of your plugin (https://docs.moodle.org/dev/Frankenstyle#Plugin_types). And it's namespaced accordingly.  
* This file is composed by a class that contains the external functions and their description functions.
* This file is composed by a class that contains the external functions and their description functions.


Line 18: Line 18:
  * PLUGIN external file
  * PLUGIN external file
  *
  *
  * @package    local_PLUGIN
  * @package    component
* @category  external
  * @copyright  20XX YOURSELF
  * @copyright  20XX YOURSELF
  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
  */
defined('MOODLE_INTERNAL') || die();
require_once($CFG->libdir . "/externallib.php");
require_once($CFG->libdir . "/externallib.php");


class local_PLUGIN_external extends external_api {
class something extends external_api {


     /**
     /**
Line 67: Line 71:
</code>
</code>


To go further, read the [[Creating_a_web_service_and_a_web_service_function|core developer tutorial]].
To go further, read this core developer tutorial: [[Creating_a_web_service_and_a_web_service_function]].
 
== Security ==
Before operating on any data in an external function, you must call external_api::validate_context() on the most specific context for the data. This will perform some sanity and security checks, as well as setup the correct theme, language and filters for rendering content. If your function only uses one context, validate it once at the start of your external function. If your function operates on multiple contexts (like a list of courses), you  must validate each context right before generating any response data related to that context (e.g. calling any $OUTPUT functions or $PAGE->get_renderer() ). Do not call require_login from an external function, that function is reserved for php scripts returning a web page. Do not call $PAGE->set_context() manually, this will generate warning notices. validate_context() is the only correct way to write external functions.
 
Also make sure you pass all arguments through external_api::validate_parameters() before using them to ensure proper cleaning/sanitisation of the input.
 
Also be sure to enforce proper capability checks everywhere - external functions are a public API.


== Example ==
== Example ==
Line 78: Line 89:


[[Category:Web_Services]]
[[Category:Web_Services]]
[[Category:API]]

Revision as of 17:39, 3 May 2020

Overview

The external functions API allows you to create fully parameterised methods that can be accessed by external programs (such as Web services API).

The external functions are located under every component\external\[optional\sub\] namespace (previously in externallib.php files). Each external function is implemented inside an individual class and is complemented by two description functions:

  • FUNCTIONNAME_parameters() which describes the parameters of the functions
  • FUNCTIONNAME_returns() which describes the return value

The description functions uses external_description classes that have been created for this purpose.

component\external\something.php

<?php

/**

* PLUGIN external file
*
* @package    component
* @category   external
* @copyright  20XX YOURSELF
* @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/

defined('MOODLE_INTERNAL') || die();

require_once($CFG->libdir . "/externallib.php");

class something extends external_api {

   /**
    * Returns description of method parameters
    * @return external_function_parameters
    */
   public static function FUNCTIONNAME_parameters() {
       // FUNCTIONNAME_parameters() always return an external_function_parameters(). 
       // The external_function_parameters constructor expects an array of external_description.
       return new external_function_parameters(
               // a external_description can be: external_value, external_single_structure or external_multiple structure
               array('PARAM1' => new external_value(PARAM_TYPE, 'human description of PARAM1')) 
       );
   }
   /**
    * The function itself
    * @return string welcome message
    */
   public static function FUNCTIONNAME($PARAM1) {

       //Parameters validation
       $params = self::validate_parameters(self::FUNCTIONNAME_parameters(),
               array('PARAM1' => $PARAM1));
       //Note: don't forget to validate the context and check capabilities
       return $returnedvalue;
   }
   /**
    * Returns description of method result value
    * @return external_description
    */
   public static function FUNCTIONNAME_returns() {
       return new external_value(PARAM_TYPE, 'human description of the returned value');
   }


}

To go further, read this core developer tutorial: Creating_a_web_service_and_a_web_service_function.

Security

Before operating on any data in an external function, you must call external_api::validate_context() on the most specific context for the data. This will perform some sanity and security checks, as well as setup the correct theme, language and filters for rendering content. If your function only uses one context, validate it once at the start of your external function. If your function operates on multiple contexts (like a list of courses), you must validate each context right before generating any response data related to that context (e.g. calling any $OUTPUT functions or $PAGE->get_renderer() ). Do not call require_login from an external function, that function is reserved for php scripts returning a web page. Do not call $PAGE->set_context() manually, this will generate warning notices. validate_context() is the only correct way to write external functions.

Also make sure you pass all arguments through external_api::validate_parameters() before using them to ensure proper cleaning/sanitisation of the input.

Also be sure to enforce proper capability checks everywhere - external functions are a public API.

Example

You will find an example of an external.php file in the web service template plugin. This plugin contains a web service hello_world function. To make testing easy for you, the plugin is distributed with a test client in the folder /client.

See also