API:Extensions

Ce document décrit la création d'un module d'API dans une extension à utiliser avec MediaWiki 1.30 ou ultérieur.

Création du module et enregistrement

Tous les modules API sont des sous-classes de ApiBase , mais certains types de modules utilisent une classe de base dérivée. La méthode d'enregistrement aussi dépend du type de module :

Modules d'action

Les modules qui fournissent une valeur pour le paramètre principal action doivent sous-classer ApiBase . Ils doivent être enregistrés dans extension.json en utilisant la clé APIModules.

Modules de format

Les modules qui fournissent une valeur pour le paramètre principal format doivent être une sous-classe de ApiFormatBase. Ils doivent être enregistrés dans extension.json en utilisant la clé APIFormatModules. Il est très rare qu'une extension ait besoin d'ajouter un module de format.

Sous-modules de requête

Les modules qui fournissent une valeur pour les paramètres prop, list, et meta à action=query doivent être des sous-classes de ApiQueryBase (s'ils ne peuvent être utilisés comme générateur) ou ApiQueryGeneratorBase (s'ils peuvent être utilisés comme générateur). Ils doivent être enregistrés dans extension.json en utilisant la clé APIPropModules, APIListModules, ou APIMetaModules.

Dans tous les cas, la valeur de la clé d'enregistrement est un objet ayant le nom du module (par exemple la valeur du paramètre) comme clé et le nom de la classe comme valeur. Les modules peuvent aussi être enregistrés conditionnellement en utilisant les accroches ApiMain::moduleManager (pour les modules d'action et de format) et ApiQuery::moduleManager (pour les sous-modules de requête).

Mise en œuvre

Préfixe

In the constructor of your API module, when you call parent::__construct() you can specify an optional prefix for your module's parameters. (In the generated documentation for a module this prefix, if any, appears in parentheses in the heading for the module.) If your module is a query submodule then a prefix is required, since a client can invoke multiple submodules each with its own parameters in a single request. Le préfixe est facultatif pour les modules d'action et de format.

Paramètres

La plupart des modules nécessitent des paramètres. Ceux-ci sont définis en implémentant getAllowedParams(). The return value is an associative array where keys are the (unprefixed) parameter names and values are either the scalar default value for the parameter or an array defining the properties of the parameter using the PARAM_* constants defined by ApiBase.

L'exemple montre la syntaxe et quelques constantes de PARAM_* parmis les plus communes.

	protected function getAllowedParams() {
		return [
			// Paramètre optionnel avec une valeur par défaut
			'simple' => 'value',

			// Paramètre obligatoire
			'required' => [
				ApiBase::PARAM_TYPE => 'string',
				ApiBase::PARAM_REQUIRED => true,
			],

			// Paramètre acceptant plusieurs valeurs dans une liste
			'variable' => [
				// Ensemble de valeurs par défaut.
				ApiBase::PARAM_DFLT => 'foo|bar|baz',
				// Toutes valeurs possibles.
				ApiBase::PARAM_TYPE => [ 'foo', 'bar', 'baz', 'quux', 'fred', 'blah' ],
				// Indique que plusieurs valeurs sont acceptées
				ApiBase::PARAM_ISMULTI => true,
				// Utiliser les messages de documentation standard ''par valeur''
				ApiBase::PARAM_HELP_MSG_PER_VALUE => [],
			],

			// A standard "limit" parameter. It's generally best not to vary from this standard.
			'limit' => [
				ApiBase::PARAM_DFLT => 10,
				ApiBase::PARAM_TYPE => 'limit',
				ApiBase::PARAM_MIN => 1,
				ApiBase::PARAM_MAX => ApiBase::LIMIT_BIG1,
				ApiBase::PARAM_MAX2 => ApiBase::LIMIT_BIG2,
			],
		];
	}

Parameters are documented using MediaWiki's i18n mechanism. See #Documentation for details.

Exécution et résultats

Le code qui actuellement implémente le module exécute la méthode execute(). This code will generally use $this->extractRequestParams() to get the input parameters, and will use $this->getResult() to get the ApiResult object to add any output to.

Query prop submodules should use $this->getPageSet() to access the set of pages to operate on.

Query submodules that can be used as generators will also need to implement executeGenerator() which is passed an ApiPageSet that should be filled with the generated pages. Dans ce cas, le ApiResult ne doit généralament pas être utilisé.

Mise en cache

Par défaut, les réponses de l'API ne peuvent pas être mises en cache ('Cache-Control: private'). Pour les modules d'action, vous pouvez autoriser la mise en cache en appelant $this->getMain()->setCacheMode(). This still requires clients pass the maxage or smaxage parameters to actually enable caching. Vous pouvez aussi forcer la mise en cache en appelant $this->getMain()->setCacheMaxAge().

Ne pas appeler ces méthodes pour les modules de requête. Vous pouvez permettre l'utilisation du cache en implémentant getCacheMode() à la place.

Dans tous les cas, assurez-vous que les données privées ne sont pas exposées.

Gestion des jetons

If your action module changes the wiki in any way, it should require a token of some kind. To have this handled automatically, implement the needsToken() method, returning the token that your module requires (probably the 'csrf' edit token). The API base code will then automatically validate the token that clients provide in API requests in a token parameter.

If you don't want to use a token that is part of core, but rather a custom token with your own permission checks, use ApiQueryTokensRegisterTypes hook to register your token.

Accès à la base de données principale

Si votre module a accès à la base de données maître, il doit implémenter la méthode isWriteMode() pour renvoyer true.

Signaler des problèmes

ApiBase comprend plusieurs méthodes pour réaliser différentes vérifications, par exemple :

• If you need to assert that exactly one of a set of parameters was supplied, use $this->requireOnlyOneParameter().

• If you need to assert that at most one of a set of parameters was supplied, use $this->requireMaxOneParameter().

• If you need to assert that at least one of a set of parameters was supplied, use $this->requireAtLeastOneParameter().

• If you need to assert that the user has certain rights, use $this->checkUserRightsAny().

• If you need to assert that the user can take an action on a particular page, use $this->checkTitleUserPermissions().

• If the user is blocked (and that matters to your module), pass the Block object to $this->dieBlocked().

But you will often run into cases where you need to raise an error of your own. The usual way to do that is to call $this->dieWithError(), although if you have a StatusValue with the error information you could pass it to $this->dieStatus() instead.

If you need to issue a warning rather than an error, use $this->addWarning() or $this->addDeprecation() if it's a deprecation warning.

Documentation

The API is documented using MediaWiki's i18n mechanism. Needed messages generally have default names based on the module's "path". For action and format modules, the path is the same as the module's name used during registration. For query submodules, it's the name prefixed with "query+".

Every module will need a apihelp-$path-summary message, which should be a one-line description of the module. If additional help text is needed, apihelp-$path-extended-description may be created as well. Each parameter will need a apihelp-$path-param-$name message, and parameters using PARAM_HELP_MSG_PER_VALUE will also need a apihelp-$path-paramvalue-$name-$value for each value.

La documentation plus détaillée sur l'API est disponible sur API:Localisation .

Les extensions peuvent aussi maintenir une documentation supplémentaire de l'API sur Wikimedia. Elle doit se trouver sur la page d'accueil de l'extension, ou s'il faut plus de place, sur des pages nommées Extension:<ExtensionName>/API, ou des sous-pages ce celles-ci (comme CentralAuth , MassMessage , ou StructuredDiscussions ). L'espace de noms API est réservé pour les API du noyau MediaWiki.

Étendre des modules du noyau

Depuis MediaWiki 1.14, il est possible d'étendre la fonctionnalité des modules du noyau en utilisant les accroches suivantes :

• APIGetAllowedParams - pour ajouter ou modifier la liste des paramètres du module
• APIGetParamDescription - pour ajouter ou modifier la description des paramètres des modules
• APIAfterExecute - pour rajouter un traiement après que le module se soit exécuté (mais avant d'avoir envoyé le résultat)
  • Utiliser APIQueryAfterExecute pour les modules prop=, list= et meta=
    • Si le module est exécuté en mode générateur, APIQueryGeneratorAfterExecute sera appelé à la place

Liste d'extensions possédant des fonctionnalités d'API

Voir Catégorie:Extensions API pour les exemples d'extensions qui s'ajoutent ou étendent l'API.

Testez votre extension

• Visitez api.php et naviguez vers l'aide générée pour votre module ou sous-module de requête. Les informations d'aide de votre extension doivent être correctes.
  • Les exemples d'URLs que vous avez fournis dans getExamplesMessages() doivent apparaître sous Exemples, essayez de cliquer dessus.
  • Enlevez des paramètres dans la chaîne de la requête et mélangez-les pour vérifier la réponse de votre extension.
• Voir Special:ApiSandbox et explorer interactivement votre API.
• Pour les informations supplémentaires concernant votre extension :

api.php?action=paraminfo&modules=myext [Essayez !]