API:Extensions/fr

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, 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  doivent sous-classer . Ils doivent être enregistrés dans   en utilisant la clé.


 * Modules de format
 * Les modules qui fournissent une valeur pour le paramètre principal  doivent être une sous-classe de . Ils doivent être enregistrés dans   en utilisant la clé  . 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,  , et   à   doivent être des sous-classes de  (s'ils ne peuvent être utilisés comme générateur) ou  (s'ils peuvent être utilisés comme générateur). Ils doivent être enregistrés dans   en utilisant la clé  ,  , ou.

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 (pour les modules d'action et de format) et  (pour les sous-modules de requête).

Préfixe
In the constructor of your API module, when you call 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. 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  constants defined by.

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

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. This code will generally use to get the input parameters, and will use  to get the  object to add any output to.

Query prop submodules should use to access the set of pages to operate on.

Query submodules that can be used as generators will also need to implement which is passed an  that should be filled with the generated pages. Dans ce cas, le  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').

This still requires clients pass the  or   parameters to actually enable caching.

Ne pas appeler ces méthodes pour les modules de requête. Vous pouvez permettre l'utilisation du cache en implémentant à 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  method, returning the token that your module requires (probably the   edit token). The API base code will then automatically validate the token that clients provide in API requests in a  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 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  pour renvoyer.



Signaler des problèmes
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.
 * If you need to assert that at most one of a set of parameters was supplied, use.
 * If you need to assert that at least one of a set of parameters was supplied, use.
 * If you need to assert that the user has certain rights, use.
 * If you need to assert that the user can take an action on a particular page, use.
 * If the user is blocked (and that matters to your module), pass the  object to.

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, although if you have a  with the error information you could pass it to  instead.

If you need to issue a warning rather than an error, use or  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  message, which should be a one-line description of the module. If additional help text is needed,  may be created as well. Each parameter will need a  message, and parameters using   will also need a   for each value.

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

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, ou des sous-pages ce celles-ci (comme , , ou ). 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 :


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



Liste d'extensions possédant des fonctionnalités d'API
Voir pour les exemples d'extensions qui s'ajoutent ou étendent l'API.



Testez votre extension

 * Visitez [/api.php 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  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 :