API:Extensions/fr

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



Création de 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. Le méthode de registre 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 en   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 en   en utilisant la clé  ,  , ou.

In all cases, the value for the registration key is an object with the module name (i.e. the value for the parameter) as the key and the class name as the value. Modules may also be registered conditionally using the (for action and format modules) and  (for query submodules) hooks.

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. For action and format modules, the prefix is optional.

Paramètres
Most modules require parameters. These are defined by implementing. 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
By default API responses are marked as not cacheable ('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. You can allow caching by instead implementing.

In either case, be sure that private data is not exposed.



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
If your module accesses the master database, it should implement the  method to return.



Signaler des problèmes
includes several methods for performing various checks, for example,


 * 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.

More details on API documentation are available at.

Extensions may also maintain extra API documentation on Wikimedia. This should be located on the extension's main page or, if more space is required, on pages named  or subpages thereof (e.g., , or ). The API namespace is reserved for the API of MediaWiki core.



Étendre des modules du noyau
Since MediaWiki 1.14, it's possible to extend core modules' functionality using the following hooks:


 * - to add or modify the module's parameter list
 * - to add or modify the module's parameter descriptions
 * - to do something after the module has been executed (but before the result has been output)
 * Use for ,   and   modules
 * If the module is run in generator mode, will be called instead



Liste d'extensions possédant des fonctionnalités d'API
See for examples of extensions that add to or extend the API.



Un test en-cours de votre extension

 * Visitez [/api.php api.php] et naviguez vers l'aide générée pour votre module ou celle du sous-module de requêtes. L'information aide de votre extension devrait être correct.
 * The example URLs you provided in  should appear under "Examples", try clicking them.
 * Omit and mangle URL parameters in the query string, check your extension's response.
 * Visit Special:ApiSandbox and interactively explore your API.
 * Visit to see additional information about your extension.