External services description - Revision history

Devdocsbot: Protected "External services description": Developer Docs Migration ([Edit=Allow only administrators] (indefinite))

2022-12-22T06:12:26Z

Protected "External services description": Developer Docs Migration ([Edit=Allow only administrators] (indefinite))

← Older revision	Revision as of 06:12, 22 December 2022
(No difference)

Devdocsbot: Update migration status and path

2022-12-22T06:10:42Z

Update migration status and path

Show changes

Mudrd8mz: Text replacement - "`" to ""`


2021-07-14T13:38:20Z
Text replacement - "<code php>" to "<syntaxhighlight lang="php">"

				
				
				
				
				
				← Older revision
				Revision as of 13:38, 14 July 2021
				
Line 167:
Line 167:
In the db/services.php of each component, is a structure something like this to describe the web service functions, and optionally, any larger services built up of several functions. In the db/services.php of each component, is a structure something like this to describe the web service functions, and optionally, any larger services built up of several functions.



<code php> <syntaxhighlight lang="php">
$functions = array( $functions = array(
     'moodle_user_create_users' => array(           //web service name (unique in all Moodle)      'moodle_user_create_users' => array(           //web service name (unique in all Moodle)
Line 198:
Line 198:



''Base description classes:'' ''Base description classes:''
<code php> <syntaxhighlight lang="php">
abstract class external_description { abstract class external_description {
     public $desc; //human readable description      public $desc; //human readable description
Line 247:
Line 247:
''Externallib.php examples:''<br/> ''Externallib.php examples:''<br/>
These examples include param/return value descriptions and function implementations. See the create_users function for difference between Mandatory/Optional/Default.   These examples include param/return value descriptions and function implementations. See the create_users function for difference between Mandatory/Optional/Default.  
<code php> <syntaxhighlight lang="php">
class moodle_group_external extends external_api { //see following chapter 'function implementation' to have a look to the external_api class class moodle_group_external extends external_api { //see following chapter 'function implementation' to have a look to the external_api class
     public static function add_member_parameters() {      public static function add_member_parameters() {
Line 402:
Line 402:
We use the clean_param function to check data.  We have added in ''moodlelib.php'' some new checks for common Moodle data so that we get better cleaning.  eg   We use the clean_param function to check data.  We have added in ''moodlelib.php'' some new checks for common Moodle data so that we get better cleaning.  eg  



<code php> <syntaxhighlight lang="php">
... ...
         case PARAM_AUTH:          case PARAM_AUTH:
Line 483:
Line 483:
As you probably understood when you read the previous chapter examples, the functions are generally stored in externallib.php files, as methods in a class that extends ''''external_api''''.  The actual file location is referenced by ''''classpath'''' in the services.php description. As you probably understood when you read the previous chapter examples, the functions are generally stored in externallib.php files, as methods in a class that extends ''''external_api''''.  The actual file location is referenced by ''''classpath'''' in the services.php description.



<code php> <syntaxhighlight lang="php">
class moodle_user_external extends external_api { class moodle_user_external extends external_api {
     public static function create_users($users)      public static function create_users($users)
Line 501:
Line 501:



external_api file: external_api file:
<code php> <syntaxhighlight lang="php">
/** /**
  * Base class for external api methods.   * Base class for external api methods.



Mudrd8mz: Text replacement - "class="nicetable"" to "class="wikitable""
2021-07-14T13:22:47Z
Text replacement - "class="nicetable"" to "class="wikitable""

				
				
				
				
				
				← Older revision
				Revision as of 13:22, 14 July 2021
				
Line 22:
Line 22:






{| class="nicetable" {| class="wikitable"
! Field ! Field
! Type ! Type
Line 70:
Line 70:






{| class="nicetable" {| class="wikitable"
! Field ! Field
! Type ! Type
Line 130:
Line 130:
Lists all functions that are available in each service. Lists all functions that are available in each service.



{| class="nicetable" {| class="wikitable"
! Field ! Field
! Type ! Type

`Mudrd8mz: Text replacement - "`" to ""

2021-07-14T13:05:53Z

Text replacement - "</code>" to "</syntaxhighlight>"

← Older revision		Revision as of 13:05, 14 July 2021
Line 187:		Line 187:
	)		)
	);		);
	</~~code~~>		</syntaxhighlight>

	The function name is arbitrary, but must follow [[Web_service_API_functions#Naming_convention\|the naming convention]]. This helps ensure that it is globally unique.		The function name is arbitrary, but must follow [[Web_service_API_functions#Naming_convention\|the naming convention]]. This helps ensure that it is globally unique.
Line 243:		Line 243:
	}		}

	</~~code~~>		</syntaxhighlight>

	''Externallib.php examples:''<br/>		''Externallib.php examples:''<br/>
Line 394:		Line 394:
	}		}
	}		}
	</~~code~~>		</syntaxhighlight>

	Note the use of Moodle-oriented PARAM_XXXX constants to define the format of each field. These are used by the validation function ''validate_parameters()'' to verify the data and throw an exception and abort the operation completely if the data changed during cleaning (ie it was malformed).		Note the use of Moodle-oriented PARAM_XXXX constants to define the format of each field. These are used by the validation function ''validate_parameters()'' to verify the data and throw an exception and abort the operation completely if the data changed during cleaning (ie it was malformed).
Line 429:		Line 429:
	}		}
	...		...
	</~~code~~>		</syntaxhighlight>

	=====Parameters types=====		=====Parameters types=====
Line 496:		Line 496:
	}		}
	}		}
	</~~code~~>		</syntaxhighlight>

	Note: there is more examples in the previous chapter		Note: there is more examples in the previous chapter
Line 524:		Line 524:
	...		...
	}		}
	</~~code~~>		</syntaxhighlight>

	=== Way to fill the database tables ===		=== Way to fill the database tables ===

Stronk7: MDLSITE-6096 - new location for external function definitions

2020-05-03T17:13:32Z

MDLSITE-6096 - new location for external function definitions

← Older revision		Revision as of 17:13, 3 May 2020
Line 5:		Line 5:

	===Service discovery===		===Service discovery===
	We store the service descriptions and a part of the function descriptions in the component/db/services.php file. Function implementations are located in externallib.php files ~~- this~~ file ~~name is not mandatory, but it is strongly recommended. externallib.php files~~ also contain the other part of the function descriptions (the function parameters descriptions).		We store the service descriptions and a part of the function descriptions in the component/db/services.php file. Function implementations are located under \component\external classes (previously in externallib.php files). These external functions, one per class (and file) also contain the other part of the function descriptions (the function parameters descriptions).

	During the upgrades the descriptions are parsed by a service discovery function that fills the database tables. Administrative UI may be used to change some configuration details. Services can also be defined via the admin UI, but it is recommended to use the new local plugin (look at the readme.txt into the Moodle local folder) when adding custom new services.		During the upgrades the descriptions are parsed by a service discovery function that fills the database tables. Administrative UI may be used to change some configuration details. Services can also be defined via the admin UI, but it is recommended to use the new local plugin (look at the readme.txt into the Moodle local folder) when adding custom new services.

Tim Hunt: /* services.php */

2020-04-21T11:55:32Z

services.php

← Older revision		Revision as of 11:55, 21 April 2020
Line 189:		Line 189:
	</code>		</code>

	The function name is arbitrary, but it ~~must be~~ globally unique ~~so we highly recommend using the component name as prefix (and "moodle" for core functions)~~.		The function name is arbitrary, but must follow [[Web_service_API_functions#Naming_convention\|the naming convention]]. This helps ensure that it is globally unique.

	The actual param description and description of returned values can be obtained from the same class by static method calls by adding '_parameters' and '_returns' to the methodname value.		The actual param description and description of returned values can be obtained from the same class by static method calls by adding '_parameters' and '_returns' to the methodname value.

Tim Hunt: /* services.php */

2020-04-21T11:53:53Z

services.php

← Older revision		Revision as of 11:53, 21 April 2020
Line 183:		Line 183:
	'functions' => array ('functionname', 'secondfunctionname'), //web service function name		'functions' => array ('functionname', 'secondfunctionname'), //web service function name
	'requiredcapability' => 'some/capability:specified',		'requiredcapability' => 'some/capability:specified',
	'restrictedusers' = >1,		'restrictedusers' => 1,
	'enabled'=>0, //used only when installing the services		'enabled'=>0, //used only when installing the services
	)		)

Marcojones: /* external_functions table */

2018-12-28T09:33:15Z

external_functions table

← Older revision		Revision as of 09:33, 28 December 2018
Line 19:		Line 19:

	===external_functions table===		===external_functions table===
	This table ~~list~~ the web service functions. It makes ~~sens~~ to ~~cal~~ it external_functions as 1 web service function <=> 1 external function. This table maps the web service function name to the actual implementation of that function.		This table lists the web service functions. It makes sense to call it external_functions as 1 web service function <=> 1 external function. This table maps the web service function name to the actual implementation of that function.

Jleyva: /* services.php */

2016-05-19T07:24:21Z

services.php

← Older revision		Revision as of 07:24, 19 May 2016
Line 175:		Line 175:
	'description' => 'create some users',		'description' => 'create some users',
	'type' => 'write',		'type' => 'write',
	'services' => array(MOODLE_OFFICIAL_MOBILE_SERVICE) // Optional, only available for Moodle 3.1 onwards. List of built-in services where the function will be included. Services created manually via the Moodle interface are not supported.		'services' => array(MOODLE_OFFICIAL_MOBILE_SERVICE) // Optional, only available for Moodle 3.1 onwards. List of built-in services (by shortname) where the function will be included. Services created manually via the Moodle interface are not supported.
	)		)
	);		);

← Older revision		Revision as of 13:38, 14 July 2021
Line 167:		Line 167:
	In the db/services.php of each component, is a structure something like this to describe the web service functions, and optionally, any larger services built up of several functions.		In the db/services.php of each component, is a structure something like this to describe the web service functions, and optionally, any larger services built up of several functions.

	<~~code~~ php>		<syntaxhighlight lang="php">
	$functions = array(		$functions = array(
	'moodle_user_create_users' => array( //web service name (unique in all Moodle)		'moodle_user_create_users' => array( //web service name (unique in all Moodle)
Line 198:		Line 198:

	''Base description classes:''		''Base description classes:''
	<~~code~~ php>		<syntaxhighlight lang="php">
	abstract class external_description {		abstract class external_description {
	public $desc; //human readable description		public $desc; //human readable description
Line 247:		Line 247:
	''Externallib.php examples:''<br/>		''Externallib.php examples:''<br/>
	These examples include param/return value descriptions and function implementations. See the create_users function for difference between Mandatory/Optional/Default.		These examples include param/return value descriptions and function implementations. See the create_users function for difference between Mandatory/Optional/Default.
	<~~code~~ php>		<syntaxhighlight lang="php">
	class moodle_group_external extends external_api { //see following chapter 'function implementation' to have a look to the external_api class		class moodle_group_external extends external_api { //see following chapter 'function implementation' to have a look to the external_api class
	public static function add_member_parameters() {		public static function add_member_parameters() {
Line 402:		Line 402:
	We use the clean_param function to check data. We have added in ''moodlelib.php'' some new checks for common Moodle data so that we get better cleaning. eg		We use the clean_param function to check data. We have added in ''moodlelib.php'' some new checks for common Moodle data so that we get better cleaning. eg

	<~~code~~ php>		<syntaxhighlight lang="php">
	...		...
	case PARAM_AUTH:		case PARAM_AUTH:
Line 483:		Line 483:
	As you probably understood when you read the previous chapter examples, the functions are generally stored in externallib.php files, as methods in a class that extends ''''external_api''''. The actual file location is referenced by ''''classpath'''' in the services.php description.		As you probably understood when you read the previous chapter examples, the functions are generally stored in externallib.php files, as methods in a class that extends ''''external_api''''. The actual file location is referenced by ''''classpath'''' in the services.php description.

	<~~code~~ php>		<syntaxhighlight lang="php">
	class moodle_user_external extends external_api {		class moodle_user_external extends external_api {
	public static function create_users($users)		public static function create_users($users)
Line 501:		Line 501:

	external_api file:		external_api file:
	<~~code~~ php>		<syntaxhighlight lang="php">
	/**		/**
	* Base class for external api methods.		* Base class for external api methods.

← Older revision		Revision as of 13:22, 14 July 2021
Line 22:		Line 22:


	{\| class="~~nicetable~~"		{\| class="wikitable"
	! Field		! Field
	! Type		! Type
Line 70:		Line 70:


	{\| class="~~nicetable~~"		{\| class="wikitable"
	! Field		! Field
	! Type		! Type
Line 130:		Line 130:
	Lists all functions that are available in each service.		Lists all functions that are available in each service.

	{\| class="~~nicetable~~"		{\| class="wikitable"
	! Field		! Field
	! Type		! Type

External services description - Revision history

Devdocsbot: Protected "External services description": Developer Docs Migration ([Edit=Allow only administrators] (indefinite))

Devdocsbot: Update migration status and path

Mudrd8mz: Text replacement - "" to ""

Mudrd8mz: Text replacement - "class="nicetable"" to "class="wikitable""

Mudrd8mz: Text replacement - "" to ""

Stronk7: MDLSITE-6096 - new location for external function definitions

Tim Hunt: /* services.php */

Tim Hunt: /* services.php */

Marcojones: /* external_functions table */

Jleyva: /* services.php */

Mudrd8mz: Text replacement - "`" to ""`

`Mudrd8mz: Text replacement - "`" to ""