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

Dans le constructeur de votre module API, lorsque vous appelez parent::__construct(), vous pouvez spécifier un préfixe optionnel pour les paramètres de votre module. (Dans la documentation générée pour un module, ce préfixe, le cas échéant, apparaît entre parenthèses dans la rubrique du module). Si votre module est un sous-module de requête, un préfixe est alors nécessaire, car un client peut invoquer plusieurs sous-modules, chacun avec ses propres paramètres, dans une seule demande. 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(). La valeur de retour est un tableau associatif où les clés sont les noms des paramètres (non préfixés) et les valeurs sont soit la valeur par défaut scalaire du paramètre ou un tableau définissant les propriétés du paramètres en utilisant les constantes PARAM_* définies par 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 => [],
			],

			// Un paramètre ''limit'' standard. Il est généralement préférable de ne pas varier de cette norme.
			'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,
			],
		];
	}

Les paramètres sont documentés à l'aide du mécanisme i18n de MediaWiki. Voir la documentation pour plus de détails.

Exécution et résultats

Le code qui actuellement implémente le module exécute la méthode execute(). Ce code utilisera généralement $this→extractRequestParams() pour obtenir les paramètres d'entrée, et utilisera $this→getResult() pour obtenir l'objet ApiResult pour y ajouter la sortie.

Les sous-modules de requête de propriétés doivent utiliser $this→getPageSet() pour accéder à l'ensemble des pages à utiliser.

Les sous-modules de requête qui peuvent être utilisés comme générateurs doivent également implémenter executeGenerator() qui est passé et ApiPageSet qui doit être rempli avec les pages générées. Dans ce cas, le ApiResult ne doit généralement 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(). Cela nécessite encore que les clients passent les paramètres de maxage ou smaxage pour activer actuellement la mise en cache. 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

Si votre module d'action modifie le wiki de quelque manière que ce soit, il doit utiliser un jeton du type donné. Pour que cela soit traité automatiquement, implémenter la méthode needsToken(), qui renvoie le jeton dont votre module a besoin (probablement le jeton d'édition 'csrf'). Le code de base de l'API va alors valider automatiquement le jeton que les clients fournissent dans un paramètre token de leur demande à l'API.

Si vous ne voulez pas utiliser un jeton qui fait partie du noyau, mais plutôt un jeton personnalisé avec vos propres contrôles d'autorisation, utilisez l'accroche ApiQueryTokensRegisterTypes pour enregistrer votre jeton.

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.

Renvoyer des erreurs

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

• Si vous devez confirmer qu'exactement un seul des paramètres d'un ensemble a été fourni, utilisez $this→requireOnlyOneParameter().
• Si vous devez confirmer que au plus un des paramètres d'un ensemble a été fourni, utilisez $this→requireMaxOneParameter().
• Si vous devez confirmer qu'au moins un des paramètres d'un ensemble a été fourni, utilisez $this→requireAtLeastOneParameter().
• Si vous devez tester que l'utilisateur a certains droits, utilisez $this→checkUserRightsAny().
• Si vous devez confirmer que l'utilisateur peut faire une action sur une page particulière, utilisez $this→checkTitleUserPermissions().
• Si l'utilisateur est bloqué (et cela importe à votre module), passez l'objet Block à $this→dieBlocked().

Mais vous allez souvent rencontrer des cas où vous devrez générer une erreur par vous même. La façon habituelle de faire cela est d'appeler $this→dieWithError(), mais si vous avez un StatusValue avec les informations de l'erreur, vous pouvez le passer à $this→dieStatus() à la place.

Si vous devez émettre un avertissement plutôt qu'une erreur, utilisez $this→addWarning() ou $this→addDeprecation() si c'est un avertissement d'obsolescence.

Documentation

L'API est documentée à l'aide du mécanisme i18n de MediaWiki. Les messages nécessaires ont généralement des noms par défaut basés sur le chemin du module. Pour les modules d'action et de format, le chemin est le même que le nom du module utilisé lors de l'enregistrement. Pour les sous-modules de requête, c'est le nom préfixé par query+ .

Chaque module aura besoin d'un message apihelp-$path-summary, qui doit être une description sur une ligne du module. Si un texte d'aide supplémentaire est nécessaire, apihelp-$path-extended-description peut également être créé. Chaque paramètre aura besoin d'un message apihelp-$path-param-$name, et les paramètres qui utilisent PARAM_HELP_MSG_PER_VALUE auront également besoin de apihelp-$path-paramvalue-$name-$value pour chaque valeur.

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

Les extensions peuvent aussi documenter les modules de leur API supplémentaire sur mediawiki.org. 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 les 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
• APIGetParamDescriptionMessages - pour ajouter ou modifier la description des paramètres des modules
• APIAfterExecute - faire quelque chose après l'exécution du module (mais avant que le résultat ne soit affiché)
  • 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 !]